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LOAD TEST SYSTEM AND METHOD 

COPYRIGHT NOTICE 

A portion of the disclosure of this patent document 
contains material which is subject to copyright protection. 
The copyright owner has no objection to the xerographic 
reproduction by anyone of the patent document or the patent 
disclosure in exactly the form it appears in the Patent and 
Trademark Office patent file or records, but otherwise reserves 
all copyright rights whatsoever. 

MICROFICHE APPENDIX 

A microfiche appendix of source code including one 
thousand three hundred nineteen (1319) frames on twenty one 
(21) sheets is included herewith. 

BACKGROUND OP THE INVENTION 

The present invention relates to the field of 
software systems. More specifically, in one embodiment the 
invention provides an improved method of load testing software 
and, especially, a system and method for scripting user actions 
for a load test. 

There are a number of different approaches to load 
testing. For example, live users may be utilized. The system 
developer hires live users and buys the hardware required (PCs 
or terminals) to drive the system. This approach, however, is 
very expensive. In order to cut costs, someone considering 
this approach usually decides to test using some fraction of 
the actual number of users that the actual system will be 
required to support, and to interpolate actual response time 
figures based on the response time of the fraction. This 
method fails largely due to inadequate testing of threshold 
conditions. Also, even if the entire number of proposed users 
can be seated and instructed to perform the test actions, it 



will be impossible to control their rates of input or 
accurately measure the response times. 

Simulations have also been used. The developer 
computes the theoretical load imposed upon the system and 
interpolates the response times and theoretical number of users 
that the system may support. This method has very little basis 
in reality and provides no confidence that its assumptions are 
correct or its results accurate. 

Canned benchmarks may also be utilized. A number of 
publicly available benchmark tests are available that exercise 
a piece of hardware and the operating system that runs it, but 
this does not allow for the testing of a particular 
application. 

From the above it is seen that an improved system and 
method for load testing software applications are needed . 

SUMMARY OP THE INVENTION 

An improved system and method for load testing 
software applications is provided by virtue of the present 
invention. The system interjects a Capture Agent that may 
capture or intercept user interface and application calls in 
order to generate a higher-level script. The script, along 
with other scripts, may be compiled and executed to simulate 
multiple users to load test software applications. 

In one embodiment, a method of producing scripts for 
load testing a software application in a client/server 
environment, includes the steps of: capturing application 
calls on the client computer, the application calls including 
application calls generated in response to the captured user 
interface calls; recording timing information of the captured 
application calls; and generating a script from the captured 
application calls that generates application calls according to 
the timing information of the captured application calls. 
Additionally, user interface calls and associated timing 
information may be captured and incorporated into the script. 

In another embodiment, a method of producing scripts 
for load testing a software application in a client/server 
environment, includes the steps of: capturing application 



calls on the client computer, the captured application calls 
including references to data stored locally on the client 
computer; identifying in the captured application calls 
references to data stored locally on the client computer; 
5 accessing the data through the references in the captured 

application calls; and generating a script from the captured 
application calls that generates application calls that include 
the accessed data in place of the references in the captured 
application calls, the script including the accessed data, 
10 Ir * another embodiment, a method of producing scripts 

for load testing a software application in a client/server 
environment, includes the steps of: capturing application 
p calls on the client computer, the captured application calls 

jg specifying information to be sent to the server computer; 

Jj 15 translating the captured application calls into source language 

S| statements; and generating a script including the source 

^ language statements that generates application calls. 

jp Additionally, the script may be user edited or compiled to 

; produce an executable load test program. 

□ 20 In another embodiment, a method of for load testing a 

yj software application in a networked computer system having a 

j±j first computer (script driver) and a second computer (system 

p under test), includes the steps of: the first computer 

executing scripts that emulate a plurality of users, the 
25 scripts including delays representative of actual user 

sessions; the first computer sending requests to the second 
computer over a network; the second computer responding to the 
requests over the network; and measuring response times of the 
second computer. Additionally, a third computer may be on the 
3 0 network to display a script directed user session in progress. 

A further understanding of the nature and advantages 
of the inventions herein may be realized by reference to the 
remaining portions of the specification and the attached 
drawings . 
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BRIEF DESCRIPTION OF THE DRAWINGS 
Fig. 1 illustrates an example of a computer system 
that may be used to execute software of the present invention; 



Fig. 2 shows a system block diagram of a typical 
computer system; 

Fig. 3 illustrates a client/server architecture ; 
Fig. 4 shows a high level flowchart of a typical 
database application; 

Fig. 5 shows the data flow of one aspect of the 

invention; 

Fig. 6 shows a high level flowchart of load testing; 
Fig. 7 shows load testing of a system under test; 
Fig. 8 shows a flowchart of the process of creating 
an executable load testing program; 

Fig. 9 shows a high level flowchart of the Capture 

Agent ; 

Fig. 10 shows a process the Capture Agent performs to 
generate a script from the capture calls; 

Fig. 11 is a typical captured database session; 

Fig. 12 shows processing of a database function; 

Fig. 13 shows a flowchart of performing load testing; 

Fig. 14 shows load testing of a system under test 
suitable for display or non-display mode; and 

Fig. 15 shows a flowchart of a process of emulating a 
user session from a script. 

DETAILED DESCRIPTION OF PREFERRED EMBODIMENTS 

Definitions : 

System - a combination of software and the hardware 
it runs on. 

Load Testing - the process of analyzing the effect of 
many users on a system. 

Response Time - the time between a user-initiated 
request and the response from the system to that request. 

Client/Server - a computer architecture where a 
networked server computer services client computers that are 
intelligent, programmable devices. 

Load Testing is an essential step in the application 
development process. It allows a developer or systems 



integrator to determine the performance and scalability of a 
system prior to the deployment of the system by measuring the 
user-perceived response time. The present invention utilizes 
user emulation to load test software applications. This 
process emulates live users by performing the activities of the 
actual users, preferably in a manner such that the actual 
system cannot differentiate between the emulated users and the 
actual users . 

Fig. l illustrates an example of a computer system 
that may be used to execute software of the present invention. 
Fig. 1 shows a computer system 1 which includes a monitor 3, 
screen 5, cabinet 7, keyboard 9, and mouse 11. Mouse 11 may 
have one or more buttons such as mouse buttons 13. Cabinet 7 
houses a CD-ROM drive 15 or a hard drive (not shown) which may 
be utilized to store and retrieve software programs 
incorporating the present invention, data for use with the 
present invention, and the like. Although a CD-ROM 17 is shown 
as the removable media, other removable tangible media 
including floppy disks, tape, and flash memory may be utilized. 
Cabinet 7 also houses familiar computer components (not shown) 
such as a processor, memory, and the like. 

Fig. 2 shows a system block diagram of a typical 
computer system. As in Fig. 1, computer system 1 includes 
monitor 3 and keyboard 9. Computer system 1 further includes 
subsystems such as a central processor 102, system memory 104, 
I/O controller 106, display adapter 108, removable disk 112, 
fixed disk 116, network interface 118, and speaker 120. Other 
computer systems suitable for use with the present invention 
may include additional or fewer subsystems. For example, 
another computer system could include more than one processor 
102 (i.e., a multi-processor system) or a cache memory. 

Arrows such as 122 represent the system bus 
architecture of computer system 1. However, these arrows are 
illustrative of any interconnection scheme serving to link the 
subsystems. For example, a local bus could be utilized to 
connect the central processor to the system memory and display 
adapter. Computer system 1 shown in Fig. 2 is but an example 
of a computer system suitable for user with the present 



invention. Other configurations of subsystems suitable for use 
with the present invention will be readily apparent to one of 
ordinary skill in the art* 

Fig. 3 illustrates a client/server architecture. A 
5 client/server system 130 includes a first computer or server 

131 and one or more second computers or clients 150. 
Typically, the clients 150 are connected to server 131 through 
a computer network 141, which may be a conventional Local Area 
Network (LAN) . Network 141 includes cabling 145 for connecting 

10 the server and each client to the network. The clients 

themselves may be similar to or the same as computer system 1. 
Each client typically includes a network connector or adapter 
143 for receiving the network cable 145, as is known in the 
art. Server 131 may also be similar to or the same as computer 

15 system 1. Because the server manages multiple resources for 

the clients, it should preferably include a relatively faster 
processor, larger mass storage, and more system memory than is 
found on each client. 

Overall operation of the system 130 is directed by a 

20 networking operating system 137, which may be stored in the 

server's system memory. In response to requests from the 
clients 150, the server 131 provides various network resources 
and services. For instance, multiple users (e.g., clients A, B 
and C) may view a database table stored in file server storage 

25 139, while another user (e.g., client E) adds a database 

record . 

The following description will focus on a preferred 
embodiment of the present invention, where the client computers 
are IBM compatible computers running Windows 3 . 1 and the script 

30 driver is a UNIX workstation (e.g., from Sun Microsystems, 

Inc.). The server provides database functions for a database 
application like those available from Oracle Corporation or 
Sybase, Inc. The network operating system that provides 
network communication may be from a vendor such as Novell. 

35 The present invention, however, is not limited to any 

particular application or any particular environment. Instead, 
those skilled in the art will find that the teachings of the 
present invention may be advantageously applied to a variety of 



other applications including spreadsheet applications, word 
processors, and the like. Moreover, the present invention may 
be embodied on a variety of different platforms, including 
Macintosh, NextStep, and the like. Therefore, the description 
that follows is for purposes of illustration and not 
limitation. 

One difficulty encountered in user emulation is the 
problem is how to develop a test script that accurately 
represents a user's activities and rates of input to the system 
being tested. This problem is complicated when the system to 
be tested is a part of a client/server application, where the 
client part of the system is located on a personal computer 
(PC) and the server part on another, usually larger, host. 

Systems provided by this invention implement a method 
of capturing user activities that are part of a client/server 
system. This method works in a way that accurately records the 
user's rates of input, client delays caused by local processing 
of data, and all other inputs necessary to correctly replay and 
replicate that user's activities to perform a load test. 
Although the particular implementation is specifically 
developed to capture particular commercially available database 
user's activities (Oracle, Sybase, etc), it can be modified for 
another database or for another type of client/server 
application. It can also be modified for another client side 
operating system such as OS/2, Windows '95, or Windows NT. 

With the invention, a single machine may be used to 
accurately simulate hundreds of users. The system creates 
scripts that represent actual users and their daily, often 
disparate, operations. With the Capture Agent, the system 
records user activities, including keystrokes, mouse movements 
and SQL requests, to create emulation scripts. The system then 
arranges a mix of scripts that represent actual users. The 
system reveals if a software application or system under test 
works. Before deployment, one can correct common difficulties 
that emerge during the application development process. The 
system may optionally chart the time one waits for screen 
responses, and may find hidden bugs and bottlenecks. 
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In a preferred embodiment, the Capture Agent captures 
Windows and SQL Application Programming Interface (API) calls. 
These user interface and application calls may be captured or 
intercepted by an in-memory replacement of API call addresses 
with Capture Agent function addresses, by a renaming of the API 
library on disk so that the Capture Agent is called in place of 
the API library which then calls the renamed library, hooks, or 
other mechanisms. As will be discussed in reference to Fig. 5, 
the Capture Agent monitors the API calls and generates a script 
that encapsulates the calls into a form that may be executed on 
another host (or script driver) . This is unique in that it is 
not merely a trace of the API calls. The calls to the API are 
monitored and re-written into a higher-level or source language 
that allows the data and a representation of the API calls to 
be recorded into a procedural script that can be compiled and 
executed. Among other things, this requires references to 
program variable addresses to be resolved by the Capture Agent 
and the data referred to to be recorded in the script. 

Another unique part of this process is that while the 
application calls (e.g., SQL API calls) are being monitored, 
the user interface calls (e.g., Windows API calls) of the 
operating system are also being monitored so that the user's 
activities may be recorded. These activities or events include 
mouse motions, button presses, key presses, as well as 
user-generated delays. The process differentiates between 
delays caused by the user (due to a user pause) , delays caused 
by the client-side of the application (due to some internal 
processing of data, for example) , and delays caused by the 
server-side of the application. Since the goal is to 
accurately emulate all of the activities of a client, these 
delays are important to the emulation of the user. Discarding 
delays caused by the internal processing of data (for example) 
will cause a higher load to be imposed on the server due to 
faster arrival times of requests. 

Fig. 4 shows a high level flowchart of a typical 
database application. The database application may be from 
such vendors as Oracle Corporation or Sybase, Inc. Although 
the client/server application described is a database 



application, other applications may be utilized with the 
present invention. For example, spreadsheet applications, word 
processors, or any other client/server application. 

Once a database application is running, the system 
receives user input at step 202. The user input may be any 
type of user input like typing characters on the keyboard or 
moving the mouse and "clicking" (depressing a mouse button) on 
a menvf selection in a Graphical User Interface (GUI) . The 
operating system typically receives these user events and /makes 
a user interface call to the appropriate application which, in 
this case, will assumed to be the database application. 

At step 204, the database application receives the 
user interface call from the operating system. The database 
application then processes the call to determine what action, 
if any, should be taken. The following describes just a few of 
the possible user interface calls that may be received. The 
calls are not intended to be an exhaustive list and may vary 
from application to application. Nevertheless, the calls are 
intended to aid the reader's understanding of a typical 
database application. 

At step 206, the database application determined that 
the user interface call is a request to logon to the database 
application. A logon typically includes the user's name and a 
password. The database application then verifies and stores 
the logon information. 

At step 208, the database application received a user 
interface call requesting to insert data into the database. 
After the database application verifies the request, the 
database application makes an application call to put the data 
in the database at step 210. The application call is sent over 
the network to the database server. 

At step 212, the database application received a user 
interface call requesting to fetch data from the database. The 
database application makes an appropriate application call to 
get the requested data from the database at step 214. The 
application call is sent over the network to the database 
server. 
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At step 216 f the database application determined that 
the user interface call is a request to logoff the database 
application. After each of the following user interface calls 
the system receives more user input at step 2 02 which may be 
5 passed on to the database application. However, if the user 

interface call specifies that the user desires to exit the 
database application, the database application exits at step 
218. 

Fig. 5 shows the data flow of one aspect of the 

10 invention. A client computer 252 is linked to a server 

computer 254 over a network. In the embodiment shown, the 
client is running Windows as an operating system and the 
database application is an SQL database like Oracle. A user 
interacts with the client through a user interface 256, here 

15 shown as Windows. As the user types characters on the keyboard 

or operates the GUI, these user events generate the appropriate 
user interface call in the form of a Windows API call to a 
client application 258. The client application is a front-end 
for the database application, which is shown as an SQL server. 

20 The front-end client application utilizes the processing power 
of the client computer in order to offload some of the 
processing required from the database server. Thus, the 
database application has a client-side application and a 
server-side application. Typically, the client application is 

25 optimized for user interaction and the server application of 

the database application is optimized for servicing multiple 
users to take advantage of the client/server architecture. 

The client application receives user interface calls 
and sends the appropriate application calls in the form of an 

3 0 SQL API call to a network transport layer 2 60. The network 

transport layer is typically a driver that formats the call for 
transmission over the network to the server. Similarly, the 
network transport layer receives data from the server sent to 
the client. 

35 An important aspect of the present invention is the 

Capture Agent. A Capture Agent 2 62 captures one or both of the 
Windows and SQL API calls during a user session. The Capture 
Agent not only intercepts the user interface and application 



calls, the Capture Agent records timing information regarding 
when the calls were sent. This allows the Capture Agent to 
generate a script 264 to emulate the user session including the 
speed in which the user input information and the speed in 
which the client computer responded locally. 

The Capture Agent may intercept user interface and 
application calls any number of ways known in the art. For 
example, the Windows API calls are intercepted by a Windows API 
call "hook" which is provided for this purpose. The SQL API 
calls may be intercepted by renaming the "real" calls so that 
the SQL API calls go to the Capture Agent. After the Capture 
Agent intercepts the SQL calls, the "real" SQL call is then 
sent so that the user session may continue. 

The script emulates a user session by being able to 
reproduce the user and application delays. This is more 
comprehensive approach than merely monitoring the network 
traffic. Preferably, the script is written in a source 
language meaning a programming language which includes human- 
readable program statements. This allows the scripts to be 
more easily edited to vary the captured user session and add 
control constructs. In a preferred embodiment, the script 
includes program statements in the C programming language. 

Fig. 6 shows a high level flowchart of load testing. 
Many of the steps shown are optional and many of the steps are 
more thoroughly discussed in the specification that follows. 
However, this high level flowchart is provided to give an 
overall view before discussing more detailed aspects of the 
present invention. 

A user session is begun on a client so that the user 
interface and application calls may be captured at step 3 02. 
The calls are captured by the captured agent which records 
timing information regarding the captured calls at step 304. 
During or after the user session, a script is generated at step 
3 06 that is capable of directing emulation of the user session. 
The Capture Agent generates the script which preferably 
includes source language statements and the timing information 
of the capture user interface and application calls. 
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At step 308, tir e sc r ipt may be -edited^ Although thils 

step is optional, it may be useful to edit the script in order 
to enhance the script (e.g., add loops) or modify the data. 
For example, if a script of a typical user session that adds a 
5 database record is captured. It may be beneficial to edit the 

script so that the script adds different database records when 
multiple copies of the script are executing. Thus, if a user 
session adds a database record for an employee named John 
Smith, the script may be edited to add a record for an employee 

10 from a data file or a random name. In this manner, when the 

script is utilized to emulate, for example, a hundred users, 
all one hundred users will not attempt to add the same database 
record. Not only would this run the risk of causing an error, 
it would not adequately emulate realistic multiple user 

15 sessions. 

The script or scripts are compiled at step 310. In a 
preferred embodiment, the scripts include source language 
statements and may be compiled into executable programs that 
emulate user sessions. Load testing may be performed with a 
20 single script or with multiple scripts. Typically, however, 

multiple scripts are utilized to simulate tens or hundreds of 
users. 

At step 312, load testing of an application or system 
under test is performed utilizing the compiled scripts. The 

25 compiled scripts are run by a script driver which is a computer 
connected to the server over a network similar to or the same 
as the network that will be utilized to connect the clients to 
the server in actual operation. 

Fig. 7 shows load testing of a system under test. A 

3 0 script driver 352 is connected to a server 354 by a network. 

In one embodiment, the script driver is a relatively fast 
computer, workstation or mainframe running the UNIX operating 
system. For example, the script driver may be a workstation 
from Sun Microsystems, Inc. which when running UNIX provides 

35 multitasking capabilities which are utilized to emulate 

multiple user sessions. 

The script driver may store multiple compiled scripts 
356. The scripts are run on the script driver as multiple 
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may include user interface calls, application calls, and timing 
information of the calls. The Capture Agent is stopped at step 
406. The Capture Agent is an important aspect of the present 
invention and its operation will be more fully described in 
reference to Figs. 9-12. 

The script may be edited at step 4 08. As mentioned 
previously, the script may be edited to insert program control 
statements like loops or to alter data so that the data more 
accurately represents user sessions. Additionally, the script 
may be edited for any number of reasons. Because the script 
contains source language statements in preferred embodiments, 
the script is not only human-readable but provides the power 
and capabilities of the source language (e.g., the C 
programming language) . Additionally, captured application 
calls for different applications from different vendors may be 
translated into the same source language. 

After the script is edited, the script is transferred 
to the script driver at step 410. The script is typically sent 
over the network to the script driver but may be input into the 
script driver utilizing other means like floppy disks. 

At step 412, the script is compiled on the script 
driver. Before the script is compiled, it may be run through a 
script preprocessor that adds source language statements or 
other information to the script to make it more suitable for 
compiling. For example, in a preferred embodiment where the 
source language is the C programming language, the scripts do 
not contain compiler preprocessor statements like "#include" or 
keywords like the curly braces and "}". The script 

preprocessor adds to or otherwise modifies the script so that 
it is ready to be compiled. 

The script or scripts are utilized to form an 
executable load testing program at step 414. If a single 
script is to be utilized to emulate a single user session, the 
script itself represents an executable load testing program for 
the user. However, typically the load testing program 
simulates multiple users running different user sessions. A 
Mix program allows more than one script to be combined to 
simulate multiple users. The definition of variables for the 
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processes so that transactions 358 are sent to the server. 
Because of the timing information in the scripts , the script 
driver may faithfully emulate the actions of multiple users. 
Therefore, the server is operating as if multiple users are 
utilizing the database application from client computers on the 
network. The server responds by sending results 3 60 to the 
script driver in response to the transactions. 

Although Fig. 7 shows a minimal system where only a 
script driver and the system under test are used for load 
testing, load testing may be performed with any number of 
client computers on the network "between" the script driver and 
the server so that the clients display user sessions as they 
are run. This aspect of the present invention is called 
"display mode" and will be discussed in more detail in 
reference to Figs. 10, 13 and 14. 

Fig. 8 shows a flowchart of the process of creating 
an executable load testing program. The executable load 
testing program is the program that operates on the script 
driver to emulate one or typically many users. The process 
steps are performed on different computers including the 
clients and the script drivers. Although these steps may be 
performed sequentially on a network including the script 
driver, clients and server. Many of the steps may be performed 
on different networks, at different locations, and at different 
times. For example, the generation of scripts does not require 
the script driver and may be performed on one or numerous 
client computers. As another example, the scripts are 
described as being edited on the client but they may be edited, 
if at all, on any computer that provides script editing 
capabilities (typically ASCII editing). Therefore, the actual 
process of executable load testing program will vary according 
to many factors which will be readily apparent to those of 
skill in the art. 

At step 402, the Capture Agent is initialized on a 
client computer. The Capture Agent is directed by a program to 
capture user interface and application calls to generate a 
script. The Capture Agent generates a script on the client 
computer according to the user session at step 404. The script 
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load testing program like the number of users, the scripts to 

be utilized for each user and any delays between the execution 

of scripts may be specified. In a preferred embodiment , the 

Mix program may be run in a batch mode or interactively. 

As an example, a very simple table may be created in 

a file called "4user.tab" to include the following: 

userl, scriptl 
user2 , scriptl 
user3, scriptl 
user4 , script2 

This table specifies that there are four users and that three 
of the users will be emulated by scriptl and one user will be 
emulated by script 2 (where "scriptl" and "script 2" are the 
compiled script names) . Although the compiled scripts may be 
started interactively either individually or utilizing a table 
file like 4user.tab, it is oftentimes easier to utilize a batch 
file. 

Multiple batch files may be created that utilize the 

4user.tab table file. For example, a batch file may be created 

that starts all the users specified by the scripts as follows: 

use 4user.tab 
start all 
wait 
quit 

The first statement directs the Mix program to utilize the 
4user.tab table. The next three statements direct the Mix 
program to start all the scripts in the table and wait for them 
to finish before quitting. 

Another batch file may be created that utilizes the 
4user.tab table file which starts three of the users specified 
by the scripts five seconds apart thirty seconds into the mix 
session. The batch file would be as follows: 

use 4user.tab 

at 3 0 start userl 

at 35 start user 2 

at 4 0 start user4 

wait 

quit 

As before, the first statement directs the Mix program to 
utilize the 4user.tab table. The next three statements specify 
the number of seconds from the beginning of the mix session 
when userl, user2 and user4 should be started. Thus, thirty 
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seconds after the mix session begins, userl, user2 and user4 
will be started five seconds apart. The wait and quit 
statements direct the Mix program to wait for the started users 
to finish before quitting. 
5 The preceding were just a couple simple examples of 

the power that the Mix program provides. When used 
interactively, the Mix program allows simple load tests to be 
quickly initiated. The batch file capability allows more 
complicated load tests to be created and saved for future use. 

10 Fig. 9 shows a high level flowchart of the Capture 

Agent. Capture is initiated by a user at step 402 of Fig. 8. 
For ease of reference, this same step is shown as step 452. 
After the user starts capture, the Capture Agent is launched at 
step 453. The Capture Agent is directed by a computer program 

15 called the Capture program. 

At step 454, the Capture Agent may check the license 
on the script driver. This step is optional but may be 
utilized to ensure that the software on the script driver is 
licensed software. In one embodiment, the script driver 

20 software is licensed only for particular computers. The 

Capture Agent then verifies that the license on the script 
driver matches the script driver computer. If the license is 
not verified, the Capture Agent will not proceed. 

The Capture Agent installs hooks to capture user 

25 interactions and database functions at step 456. Thus, the 

Capture Agent installs or sets up whatever hooks or 
interception mechanisms are needed to capture user interface 
and application calls. The "hook" API call may be utilized to 
capture Windows API calls and renaming SQL API calls may be 

3 0 utilized to capture SQL API calls. Other mechanisms may be 

utilized depending on the nature of the computer architecture, 
operating system, network operating system, and application to 
be tested. 

At step 458, the Capture Agent monitors user 
35 interface and application calls to generate a script. The 

Capture Agent captures or intercepts the calls and timing 
information of when the calls were sent. In this manner, the 
generated script is able to reproduce the user session 
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including the timing of the calls. The process of generating 
the script from the captured user interface and application 
calls will be described in more detail in reference to Fig. 10. 

Capture is stopped by a user at step 406 of Fig. 8. 
5 For ease of reference, this same step is shown as step 4 60. 

After the user stops capture, the Capture Agent uninstalls the 
hooks to capture user interactions and database functions at 
step 453. The hooks are uninstalled so that the client will be 
more in the condition before the Capture Agent was launched. 

10 The Capture Agent exits or ceases to run at step 464. 

Fig. 10 shows a process the Capture Agent performs to 
generate a script from the capture calls. At step 502, the 
user interface and application calls are captured. Timing 
information regarding when the calls, were captured is recorded 

15 at 504. The timing information may include or be used to 

calculate think time for user interface calls and application 
processing time for application calls. 

The term "think time" is used to refer to the time 
starting when the computer is able to accept input from a user 

20 and ending when the user enters (via the enter key or utilizing 

mouse buttons) commands or data (e.g., an event). For example, 
if it takes 75 seconds for a user to input information or 
otherwise produce a Windows API call, then a think time of 75 
seconds may be recorded. In a preferred embodiment, the 

25 present invention provides many options relating to think time. 
For example, a uniform think time may be specified at the 
beginning of the script so that there are less time pressures 
during a user script that generates a script. Additionally, 
the Capture Agent may be instructed to only add think times if 

3 0 the think time is longer than a specified amount of time. 

The term "application processing time" is used to 
refer to the time starting when a user interface call is 
received from the user and ending when the client application 
responds locally, for example by redrawing a window on the 

3 5 display. The application processing time does not refer to the 
time that the server takes to process an SQL call. For 
example, if it takes 0.4 seconds for the client to bring up a 
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window used for fetching data, then a application processing 
time of 0.4 second may be recorded. 

The think and application processing times are 
utilized to emulate a user session in "non-display mode". In 
5 non-display mode, the script driver communicates directly with 

the server as shown in Fig. 7. Because a client computer is 
not performing the client application functions, the user input 
to the client application is not utilized. Instead, the think 
and application processing times are utilized. 
10 In display mode, at least one client computer accepts 

the user input to the client application and reproduces the 
screen displays. This arrangement is shown in Fig. 14. Thus, 
n in display mode, the script driver communicates with the server 

J3 through a client computer which may be very useful during load 

J1J15 testing of a system. Display mode or non-display refers to a 

SJ single emulated user session or script. Consequently, some 

w scripts may be run in display mode while other scripts are run 

jj in non-display mode. Of course, display mode requires that a 

f client be available so the actual number may be limited by the 

]~J20 hardware available. 

Rj In order to illustrate the effect of display mode and 

'H non-display mode on the script, the following script segment 

p will be analyzed: 

25 Think(2.026) ; 

LeftButtonPress (459 , 616) ; 
AppWait(0.22) ; 
WindowRcv ( "CwPtPt " ) ; 
... 

3 0 The Think statement indicates the user took 2.02 6 seconds to 

click on the left mouse button as indicated by the following 
LeftButtonPress statement. The LeftButtonPress statement 
indicates that the user pressed the left mouse button at those 
coordinates. The AppWait statement indicates the client 

3 5 computer took 0.2 2 seconds to redraw a window as indicated by 

the following WindowRcv statement. The WindowRcv statement 
indicates that certain windowing events were taken in response 
to the LeftButtonPress. The parameters of the WindowRcv 
function are standard Windows two-letter pneumonics (e.g. , "Cw" 

4 0 means create window and "Pt" means paint) . 
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When the above script is run in display mode, the 
LeftButtonPress command will be sent to a client computer after 
the indicated think time and the WindowRcv command instructs 
the script driver to wait until the indicated windowing events 
occur. As the script is actually driving a client computer and 
waiting for the client application to perform, the AppWait 
f unct ion is ignored . 

When the above script is run in non-display mode, 
only the Think and AppWait statements are executed. The script 
driver waits the appropriate times to emulate the user session 
but the user interface calls and any responses to them are not 
utilized. All the scripts in Fig. 7 would be run in non- 
display mode as there is no client to display a script in 
progress. In Fig. 14, scripts may be run in display and non- 
display mode as there is at least one client to display a 
script in progress. 

Additionally, the Capture Agent may be instructed to 
only capture the application calls (e.g., SQL API calls). This 
may be done to conserve space in the script files. Thus, the 
above script would not include the LeftButtonPress statement. 
However, the Think statement would still be present so that the 
script delays time associated with user input time. The script 
may then only be run in non-display mode as the user interface 
calls are not present in the script. 

Although a user may physically operate a client 
computer while generating a script for a user session, the 
present invention may also be utilized with a GUI tester. A 
GUI tester is a program that takes over the inputs to an 
application in order to test it. The Capture Agent may be 
utilized with a GUI tester so that the GUI tester operates the 
client application and the Capture Agent generates a script. 
Thus, the present invention may be used in conjunction with GUI 
testers and does not require that a user operate the client to 
generate a script for a user session. Accordingly, the terms 
"user session", "user interface call" and the like, do not 
imply that a living user must be operating the client. 

Still referring to Fig. 10, pointers in the 
application calls to client data are dereferenced at step 506. 
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Many application calls include references or pointers to data 
that is stored locally on the client. The Capture Agent 
dereferences these pointers (accesses the data referenced) and 
places the data in the script. For example, the following is a 
5 script segment including SQL calls: 

Open(LOGl, CUR1) 

Parse (CUR1, "INSERT INTO CUSTOMERS (ID, FIRST_NAME, 
LAST_NAME, ADDRESS_LINE_1 , ADDRESS__LINE_2 , 
10 ADDRESS_LINE_3 , PHONE_NUMBER , FAX_NUMBER, 

COMM_PAID__YTD, ACCOUNT JBALANCE , COMMENTS) VALUES 
(rid, rfname, rlname, raddrl, :addr2, raddr3, :phno, 
: f axno , : cytd , : bal , : com) " ) ; 



15 Bind(CURl, 

Bind(CURl, 
Bind(CURl, 
Bind(CURl, 
Bind(CURl, 

2 0 Bind(CURl, 

Bind(CURl, 
Bind(CURl, 
Bind(CURl, 
Bind(CURl, 

25 Bind(CURl, 

Data(CURl, 
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CSset(CURl, MAXARRSIZE, 1) ; 

" rid", STRING, 4 0); 

•rfname", STRING, 21); 

" r lname" , STRING, 21) ; 

addrl", STRING, 21); 

1 r addr2 " , STRING , 21); 

tf :addr3", STRING, 21); 

phno", STRING, 16); 

faxno", STRING, 16); 

" r cytd " , STRING , 4 0); 

rbal", STRING, 40) ; 

" r comm" , STRING , 241); 

, "555 J John J Smith! 123 Elm St* {Any town, MD 
12345jUSAj555»555j555»5555j9000j5000SNo comments") ; 
Exec(CURl) ; 

Close (CUR1) ; 



The above script include source language statements in the C 
programming language. The statements add a new data record 
John Smith into CUSTOMERS • The statements correspond very 
closely to actual SQL API calls. However, in actual SQL API 
35 calls, the Bind statements may have pointers to the data for 

John Smith on the client computer (e.g., the Bind statements 
may have pointers as parameters) . 

The Capture Agent identifies the pointers, 
dereferences the pointers to access the data, and automatically 
generates the Data statement which includes the accessed data. 
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In this way, the script driver is able to replicate the user 
session without requiring access to the client's memory, which 
is typically unavailable during load testing. Another 
advantage is that by dereferencing the pointers and placing the 
5 accessed data in the script, the script may be more easily 

edited so that each copy of the script will add different 
customers to the database when run. This may be done by 
filling in the data statement from a file or using some kind of 
random data. 

1° At step 508, the script is generated. The script may 

be generated during and after a user session. In other words, 
the script may be generated at the end of a captured user 
session, during the captured user session, or both. The script 
is typically saved onto the hard drive of the client computer. 

15 Fig. 11 is a typical captured database session. Once 

the client application of the database application is running 
on the client, a Think timer is started at step 552. The user 
inputs data at step 553 until a terminating character (e.g., 
the enter key) or action (e.g., clicking a mouse button) has 

2 0 been taken. 

After the user is finished inputting data, the Think 
timer is stopped at 554. The user input in the associated user 
interface call is recorded at step 555. If the user input 
indicates the user wants to quit the application at step 556, 
25 the application terminates. Otherwise, an Application 

Processing timer is started at step 558. 

At step 559, the user input in the form of the user 
interface call is sent to the client application. Once the 
client application receives the user interface call, the 

3 0 application performs whatever processing is required at step 

560. For example, the user interface call may specify to 
perform a database function as shown in step 562 or to display 
results in step 564. The database function typically requires 
the client application to send a request to the server via the 
35 network. The processing of a database function will be 

described in more detail in reference to Fig. 12. 



The client application continues to process the user 
interface call until all the processing has been done. The 
processing has been completed at step 566. 

Fig. 12 shows processing of a database function. At 
step 602 , the client application calls a database function 
(i.e., an application call). In a preferred embodiment, the 
database function is in the form of an SQL API call and the 
database function calls a substitute database function so that 
the Capture Agent can capture or intercept the call. The 
substitute database function is called at step 604. 

The Application Processing timer is stopped at step 
606. Information being sent to the database server in the 
database function is saved at step 608. The information 
includes the database call and any data that is referenced 
through pointers in the call. At step 610, the real database 
function is called. 

At step 612 , a determination is made as to whether 
the database function resulted in an error from the server. 
For example, the error may be cause by an incorrect or ill- 
formed database function call. However, when capturing a user 
session, a user may generate an error. In order to reproduce 
the user session, the script should also do the same actions to 
generate the error. These errors though are expected so the 
script sets an error condition (e.g., a flag) to CONTINUE at 
step 618. When the script later encounters this error during 
execution, the script will check the error condition to see if 
it is set to CONTINUE. If the error condition is set to 
CONTINUE, the script knows that the error was expected and 
continues. 

If the database function did not result in an error 
from the server, the error condition is set to EXIT at step 62 0 
which instructs the script to exit if it encounters an error 
because it is unexpected. The error condition does not have to 
be set for each database function but may only be set when the 
error condition needs to be changed. Typically, most database 
functions will not generate an error so the error condition 
will usually be set to EXIT. The script will then exit when an 
unexpected error occurs during script execution. 
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At step 622, data coming back from the database 
server (e.g., results) are saved. Script statements are then 
generated at step 624* Once the script statements are 
generated, the Application Processing timer is started at step 
5 626 and control is returned to the client application at step 

628. 

Fig. 13 shows a flowchart of performing load testing. 
The flowchart assumes that there are already compiled scripts 
resident on the script server. At step 652, a determination is 

10 made whether the load test should be performed in display mode. 

In order for the load test to be performed in display mode, 
there should be at least one client computer on the network as 
shown in Fig. 14. For each client that will display the script 
in progress, a Display program is started on the client at step 

15 654. 

The Display program is designed to accept input from 
the script driver to simulate a live user. The input is 
generated by the script and was typically captured from a 
previous user session. 

20 At step 656, the Mix program is run. The Mix program 

allows, either interactively or in batch files, more than one 
script to be executed on the script driver. The Mix program is 
optional but is typically run to simulate multiple users 
interacting with the server. A flag or parameter is set for 

25 each script that will be executed in display mode so that the 

script driver sends the appropriate inputs to the client. 

Each script that executes on the script driver 
creates a log file at step 660. A report may be generated from 
the log files which includes information such as server 

3 0 response time and system throughput. In a preferred 

embodiment, the log files are ASCII files on the server so that 
third party statistical and graphics programs may be utilized 
to create custom reports. 

At step 664, a determination may be made whether to 

35 rerun another load test. For simplicity, the flowchart shows a 

return to step 656 to run the Mix program and possibly select a 
different set of users, number of users, user start times, and 
the like. However, this should not imply that a return to many 
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of the other steps is not possible . For example , a different 
client may be selected to run the display program at step 654 
or a new user session may be captured on the client at step 402 
of Fig. 8. 

5 Fig, 14 shows load testing of a system under test 

suitable for display or non-display mode. A script driver 702, 
clients 704 and a server 706 are connected by a network. The 
script driver may store multiple compiled scripts 708. Scripts 
that are run in display mode send user interface calls 710 to 

10 one of the clients 704. The clients then display the screen 

displays that occur during the emulated user session and also 
send transactions 712 to the server. The server sends results 
714 to the clients in response transactions 712. The clients 
704 forward results 714 to the script driver. 

15 Scripts that are run in non-display mode send 

transactions 718 directly to the server. the server sends 
results 72 0 to the script driver in response to transactions 
720. Transactions 712 and 718 do not differ except for the 
source of origin of the transactions being the script driver or 

20 clients, respectively. 

Fig. 15 shows a flowchart of a process of emulating a 
user session from a script. The scripts execute on the script 
driver with each script representing a user session that was 
typically captured by the Capture Agent. In a preferred 

25 embodiment, the scripts are compiled and include source 

language statements so the execution of a script is the 
execution of a computer program. The scripts may contain 
different control statements including loops and branches so 
there is no "one" process flow of a script. The script process 

30 in Fig. 15 is presented to illustrate a simple script. 

At step 752, the script starts and begins executing 
the compiled source language statements. If there are more 
functions or statements at step 754, the functions are 
executed . 

35 A database function is specified at step 756. The 

database function is translated into the appropriate 
application call (e.g., SQL API call) which is sent to the 
server via a network transport layer. 
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User processing is specified at step 760, The user 
processing may include Think delays, Pointer (e.g., mouse) 
delays or Typerate (speed of typing) delays. The script may 
have any of these delays globally defined at the beginning of 

5 the script. If the script is executed in display mode, the 

specified user interface call or calls will also be executed or 
sent at step 762 after the delays. 

Application processing is specified at step 764. An 
application processing delay (e.g., AppWait) will be performed 

0 at step 766 if the script is executed in non-display mode. If 

the script is executed in display mode, the script will wait 
for the client to return from generating the window displays. 

Once all the functions or statements in the script 
have been executed, the script creates a log file at step 768. 

5 The log file may be created and written to as the script 

executes but the step is shown at the end for simplicity. 
After the log file has been created, the script exits at step 
770. 

Appendix 1 includes source code for a computer 
0 software product that includes the Capture Agent that captures 

user interface and application calls as well as other aspects 
of the present invention. Appendix 2 is a script development 
guide. Appendix 3 is a multi-user testing guide. Appendix 4 
is a reference guide as well as other related materials. 
5 The above description is illustrative and not 

restrictive. Many variations of the invention will become 
apparent to those of skill in the art upon review of this 
disclosure. Merely by way of example the invention is 
illustrated with regard to database applications, but the 
0 invention is not so limited. The scope of the invention 

should, therefore, be determined not with reference to the 
above description, but instead should be determined with 
reference to the appended claims along with their full scope of 
equivalents. 
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WHAT IS CLAIMED IS: 



1 1. In a computer system having a server computer 

2 and a client computer, a method of producing scripts for load 

3 testing a software application, comprising the steps of: 

4 capturing application calls on the client computer, 

5 the application calls including application calls generated in 

6 response to user interactions; 

7 recording timing information of the captured 

8 application calls; and 

9 generating a script from the captured application 

10 calls that generates application calls according to the timing 

11 information of the captured application calls. 

1 2. The method of claim 1, setting a timer to 

2 determine timing information of the captured application calls 

1 3. The method of claim 1, further comprising the 

2 steps of: 

3 capturing user interface calls on the client 

4 computer ; 

5 recording timing information of the captured user 

6 interface calls; and 

7 generating the script from the captured user 

8 interface calls that generates user interface calls according 

9 to the timing information of the captured user interface calls 

1 4. The method of claim 3, setting a timer to 

2 determine timing information of the captured user interface 

3 calls. 

1 5, The method of claim 1, further comprising the 

2 step of setting a flag in the script if an error is generated 

3 during script generation . 



27 

1 6. The method of claim 5, further comprising the 

2 step of ignoring an error generated during script execution if 

3 the flag indicates the script was also generated during script 

4 generation. 

1 7, The method of claim 1, further comprising the 

2 step of executing a plurality of scripts to emulate a plurality 

3 of users. 

1 8. The method of claim 1, further comprising the 

2 step of creating a report of response times of the server 

3 computer . 

1 9. The method of claim 1, wherein the captured user 

2 interface calls are Windows API calls. 

1 10. The method of claim 1, wherein the captured 

2 application calls are SQL API calls. 

1 11. A computer program that produces scripts for 

2 load testing a software application, comprising: 

3 computer readable code that captures application 

4 calls on a client computer, the application calls including 

5 application calls generated in response to user interactions; 

6 computer readable code that records timing 

7 information of the captured application calls; and 

8 computer readable code that generates a script from 

9 the captured application calls that generates application calls 

10 according to the timing information of the captured application 

11 calls; 

12 wherein the computer readable codes are stored on a 

13 tangible medium. 
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1 12, In a computer system having a server computer 

2 and a client computer, a method of producing scripts for load 

3 testing a software application, comprising the steps of: 

4 capturing application calls on the client computer, 

5 the captured application calls including references to data 

6 stored locally on the client computer; 

7 identifying in the captured application calls 

8 references to data stored locally on the client computer; 

9 accessing the data through the references in the 

10 captured application calls; and 

11 generating a script from the captured application 

12 calls that generates application calls that include the 

13 accessed data in place of the references in the captured 

14 application calls, the script including the accessed data, 

1 13, The method of claim 12, wherein the references 

2 in the captured application calls are pointers, 

1 14. The method of claim 12, wherein the captured 

2 application calls are SQL API calls. 

1 15. The method of claim 12, wherein the script 

2 includes source language statements. 

1 16. The method of claim 15, further comprising the 

2 step of user editing the script. 

1 17. The method of claim 15, further comprising the 

2 step of compiling the script into an executable load test 

3 program . 

1 18. The method of claim 12, further comprising the 

2 step load testing a system utilizing a plurality of scripts. 
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1 19. A computer program that produces scripts for 

2 load testing a software application, comprising: 

3 computer readable code that captures application 

4 calls on the client computer, the captured application calls 

5 including references to data stored locally on the client 

6 computer ; 

7 computer readable code that identifies in the 

8 captured application calls references to data stored locally on 

9 the client computer; 

10 computer readable code that accesses the data through 

11 the references in the captured application calls; and 

12 computer readable code that generates a script from 

13 the captured application calls that generates application calls 

14 that include the accessed data in place of the references in 

15 the captured application calls, the script including the 

16 accessed data; 

17 wherein the computer readable codes are stored on a 

18 tangible medium. 

1 20. In a computer system having a server computer 

2 and a client computer, a method of producing scripts for load 

3 testing a software application, comprising the steps of: 

4 capturing application calls on the client computer, 

5 the captured application calls specifying information to be 

6 sent to the server computer; 

7 translating the captured application calls into 

8 source language statements; and 

9 generating a script including the source language 
10 statements that generates application calls. 

1 21. The method of claim 20, further comprising the 

2 step of translating captured application calls for different 

3 applications into a same source language. 

1 22. The method of claim 20, further comprising the 

2 step of capturing user interface calls on the client computer. 
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1 23. The method of claim 22, further comprising the 

2 step of translating the captured user interface calls into 

3 source language statements. 

1 24. The method of claim 23, wherein the script 

2 generates user interface calls. 

1 25. The method of claim 20, wherein the source 

2 language statements are in the C programming language. 

1 26. A computer program that produces scripts for 

2 load testing a software application, comprising: 

3 computer readable code that captures application 

4 calls on the client computer, the captured application calls 

5 specifying information to be sent to the server computer; 

6 computer readable code that translates the captured 

7 application calls into source language statements; and 

8 computer readable code that generates a script 

9 including the source language statements that generates 

10 application calls; 

11 wherein the computer readable codes are stored on a 

12 tangible medium. 

1 27. In a networked computer system having a first 

2 computer (script driver) and a second computer (system under 

3 test) , a method of for load testing a software application, 

4 comprising the steps of: 

5 the first computer executing scripts that emulate a 

6 plurality of users, the scripts including delays representative 

7 of actual user sessions; 

8 the first computer sending requests to the second 

9 computer over a network; 

10 the second computer responding to the requests over 

11 the network; and 

12 measuring response times of the second computer. 
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1 28. The method of claim 27, further comprising the 

2 step of a third computer on the network displaying a script 

3 directed user session in progress* 

1 29. The method of claim 27, further comprising the 

2 step of selecting a display mode where a third computer on the 

3 network displays a script directed user session in progress. 



LOAD TEST SYSTEM AND METHOD 



ABSTRACT 

An improved system and method for load testing 
software applications is provided- The user interface and/or 
application calls are captured to generate a script to emulate 
a user session. The script may include source language 
statements and, with or without editing, may be compiled into 
an executable script. Multiple scripts may be executed on a 
script driver to simulate multiple users to load test a system. 
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1.0 Welcome to EMPOWER/CS 

Welcome to EMPOWER/CS, PERFORMIX Inc/s full-featured solution for efficient 
client/server load testing. With EMPOWER/CS, you can emulate multiple users 
from a single load testing machine to accurately measure response time and 
throughput of your client/server environment. EMPOWER/CS captures and 
replays actual client/server activities running from Microsoft Windows PCs. It 
stress tests applications and the database server by emulating multiple PCs that 
interact with the server and then measures client/server performance by 
summarizing response times. 

Until now, client/server load testing required assembling individual PCs for each 
system-supported user, which coujd involve up to hundreds or thousands of PCs. 
With EMPOWER/CS, this costly and cumbersome process is reduced to one UNIX 
driver machine that emulates as many PCs needed to test your entire client/server 
environment. 

You can use EMPOWER/CS to load test your client/server applications during the 
entire cycle of development, to determine your database servers performance 
under peak load conditions, and to help determine future needs of your 
client/ server environment. 

This User s Guide is designed to help you understand the testing processes and 
capabilities of EMPOWER/CS and to guide you through efficient client/server load 
testing. 



1.1 Organization of the EMPOWER User's Guides 

The complete documentation for EMPOWER/CS includes three user's manuals 
which contain general use information, installation instructions, technical reference 
material, and examples. The following list identifies each user manual: 
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EMPOWER/CS Script Development 

Describes how to create and execute scripts to perform realistic load tests on your 
client/server environment. This process involves using the EMPOWER/CS tools, 
Capture and Cscc, and editing and enhancing your scripts 

Multi-User Testing 

Describes how to use the multi-user tools Mix, Extract, Report, Draw, Monitor, and 
Global Variables (GV) for emulating realistic loads and measuring performance 

Reference 

Describes commands, functions, and possible error messages for EMPOWER/CS. 
This manual also includes information for contacting PERFORMIX technical support 



1.2 Organization of this Manual 

EMPOWER/CS Script Development is divided into the following sections: 



Section 1: 
Section 2: 

Section 3: 

Section 4: 

Section 5: 

Section 6: 
Section 7: 

Section 8: 



Welcomes you to EMPOWER/CS 

Introduces you to EMPOWER/CS and load testing for 
client/ server environments 

Outlines the procedure for installing EMPOWER/CS and 
setting up the testing environment 

Describes the EMPOWER/CS tool, Capture, which 
captures user and PC activities to build executable scripts 

Describes the EMPOWER/CS tool, Cscc, which compiles 
your scripts into an executable format 

Describes the processes for executing scripts 

Describes script content and methods for editing your 
scripts including step-by-step examples 

Describes the EMPOWER/CS Windows tools 
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1.3 User's Guide Conventions 



The conventions followed in this User Guide are listed below: 



Regular Font 
Aria! Font 

Mono-spaced Font 

Bold mono-spaced font 

[-S scriptid] 

(I) 



Endf unction ( ) 



Parse ( ; 



cscc 



Capture 



Used for all regular body text 

Represents elements of the MS Windows 
environment such as pushbuttons, window titles, 
user entries, etc 

Used for all command, function, and file names; for 
all examples; and, generally, for any computer 
generated text 

In examples, represents entries made by the 
EMPOWER/CS user 

In command syntaxes, text within these square 
brackets represents optional command parameters 

Vertical lines separate command parameter choices 

Within scripts, the ellipsis marks indicate that some 
script content was left out for brevity 

Parentheses are included with script functions 
mentioned in regular body text For most functions, 
one or more parameters will be listed in the 
parentheses when the function is used in a script 

EMPOWER/CS script functions use initial 
capitalization 

EMPOWER/CS command names use all lowercase 
letters 

When an EMPOWER/CS tool is mentioned within 
regular body text, it is shown in regular font with 
initial caps 
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The term, "SUT," refers to your client/server system under test. The client/server 
SUT includes the database server and the database(s) on that server used for your 
emulation. 
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2.0 Introduction to Load Testing with 

EMPOWER/CS 

EMPOWER/CS tests the performance of a client/server application or system by 
emulating application activity of multiple PC users and by gathering response time 
data. Using EMPOWER/CS eliminates the need for many PCs to stress test your 
client/ server system under test (SUT) because you can emulate multiple PC users 
on a single UNIX driver machine applying a realistic load to the SUT. 
EMPOWER/CS tools allow you to capture actual user activity in a script file, 
combine and execute several scripts at once, and collect performance statistics. 



2.1 Why Use EMPOWER/ CS? 

You can use EMPOWER/CS to support applications development, computer 
purchase decisions, capacity planning, and product demonstrations. 



2.1.1 Applications Development 

After you develop an application, most problems do not arise until your customer 
tries to use the application during peak load conditions. Load testing with 
EMPOWER/CS measures the true scalability and performance of new 
client/ server applications and systems before they are introduced to actual users. 
By emulating multiple users with EMPOWER/CS, you can identify problems and 
defects from the very beginning of the development cycle up to new releases of 
the product. 

Companies that do not load test their client/server products risk introducing 
applications to the marketplace that fail to meet critical user expectations. 
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EMPOWER/CS prevents such costly weaknesses in fielded applications, thus, 
improving software quality and customer satisfaction. 



2.1.2 Computer Purchase Decisions 

The lack of practical load testing tools has posed a serious dilemma for companies 
wishing to migrate from a mainframe system to a client/server environment. 
EMPOWER/ CS reduces this costly load testing process to one driver machine, 
allowing you to test a system efficiently. You can apply your current and future 
client/ server workloads before purchasing an application or system. 

EMPOWER/CS provides price performance information by determining the 
number of client/ server transactions per unit time for specified user activities. For 
instance, you can determine how long it takes to perform the same query for ten, 
one hundred, or even one thousand users. Evaluators may use such data and cost 
information associated with software and users to determine the value of the 
client/server system under test (SUT) in terms of dollars per transaction. 
EMPOWER/CS is more valuable than other evaluation tools because it generates 
data that characterizes your application. 



2.1.3 Capacity Planning 

EMPOWER/CS can estimate the amount of processing power needed to meet 
your future load requirements by performing tests that replicate both the current 
and future workloads of your client/server environment. Load testing can be 
executed on your current system to determine if your system must grow with your 
planned workload. 
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2.1.4 Product Demonstrations 



EMPOWER/CS is highly effective in demonstrating your client/server product or 
application to potential customers. A performance test emulating actual user and 
database activity provides your customers with a feeling of confidence that your 
client/server application will perform in the field as promised. This is especially 
useful if you do not have reference sites for your potential customers' workload. 



EMPOWER/CS places a capturing agent on a Microsoft Windows PC that records 
dialog between the PC and the SUT. From this interaction, the capturing agent 
builds a script that is suitable for executing multi-user tests: 



2.2 How Does EMPOWER/CS Work? 





SUT 



Script 
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Because EMPOWER/CS requires the multi-tasking features of UNIX to run multiple 
scripts, scripts are transferred to a UNIX driver machine where they are compiled 
and executed With EMPOWER/CS, the UNIX driver can combine and execute 
several scripts simultaneously, and the scripts can be edited and enhanced to 
emulate more realistic client/server activity. Only the UNIX script driver and your 
SUT are required for the emulation. 

When the script is executed on the UNIX script driver, it acts as a client to interact 
with the SUT emulating captured PC activities. As the script executes, the SUT 
assumes it is servicing SQL requests from an actual PC, thus, creating a true multi- 
user test environment: 






UNIX Script Driver SUT 
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You need a PC only for capturing user activity and, optionally, for Display mode 
which displays emulated activity on screen as a script executes: 




2.3 Testing Process 

The first step for load testing your client server environment with EMPOWER/CS 
is capturing PC and SUT interactions into a script file. When capturing scripts, 
changes to your client/server application are not required. The capturing tool only 
requires that you perform the most common user activities. To build complete 
scripts, EMPOWER/CS records mouse and keyboard strokes, SQL requests to the 
SUT, and data returned to the PC. The resulting scripts are transferred to the UNIX 
script driver. 

Before executing scripts, you must compile them on the UNIX driver machine. The 
executing script binary replaces the PC to interact with the SUT. 
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Then, to simulate the actual load on the client/server environment, you should 
combine and execute multiple scripts. You can duplicate individual scripts to 
simulate multiple users performing similar activities, and you can combine different 
scripts to emulate a complex set of user and application activity. 

To produce the most accurate test results, you can edit your scripts to make them 
unique to your environment. Because EMPOWER/CS scripts are actually C 
language programs, they can be enhanced or supplemented as required. You can 
vary scripts by branching, altering data, and inserting loops. You also can change 
values entered in queries and updates during Capture (because in reality, all users 
would not query and update identical records continuously). User entries can be 
substituted by generating random values, sharing pools of input on the driver, 
accessing data returned from the SUT, or passing data between the scripts. 

You can control the rate of transactions applied to the SUT while tests execute. 
Such controls as typing rate, thinking delays, constant and variable pacing, and 
synchronization points can be set at the start of a test and then adjusted as needed 
Adjusting controls during the test permits load balancing and tuning. 

While tests are running, you can monitor scripts to verify progress, debug running 
scripts, and examine current response times. After your tests execute, you can 
generate reports that summarize interactive response time and peak throughput 
supported by your system. Valuable performance information such as response 
time averages, minimums, maximums, percentiles, transaction categories, and client 
processing times can be assembled within minutes. 



2.4 EMPOWER/CS Tools 

EMPOWER/CS includes and uses the following tools: Capture, Cscc, Mix, Extract, 
Report, Draw, Monitor, and Global Variables. 
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2.4.1 Capture 

Capture is executed from Microsoft Windows on your PC to capture actual PC and 
SUT interactions in a script file. You simply activate the Capture icon, perform the 
user activity you wish to test, and then transfer your captured script file to the UNIX 
driver. Many options are available when capturing your script such as inserting user 
think times into the script file, adding comments and functions to the script, and 
automatically transferring scripts to the UNIX driver. The following example depicts 
the Capture command window. 



Capture 



File Help 




A sample EMPOWER/CS script file, scriptl.c, follows. Such user and database 
activity as mouse events, logging on to the database, and processing a query were 
captured into this script (Some script content was left out for brevity): 
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/* EMPOWER/CS VI. 0.1 Remote Terminal Emulator Script */ 



Typerate { 5 ) ; 
Pointerrate(150) ; 
Thinkuniform{l,2.5) ; 
Seed(getpid{) ) ; 
Timeout (3 00, CONTINUE), 
Dberror (CONTINUE} ; 
Unset (NOTIFY) ; 

Beginscenar io ( " scriptl " ) ; 



/* Typing delay in CPS */ 

/* Pointerrate in PPS */ 

/* Think delay */ 

/* Seed random number generator */ 

/* What to do if DB transaction takes too long */ 

/* What to do on Database errors */ 

/* Don't display warnings. I'll use Mon to find them */ 



InitialWindow{0, "Desktop" , 0 , 0, 640, 480) ; 
InitialWindowd, "MS-DOS Prompt " , 21, 408 , 0 , 0) ; 
InitialWindow{2, "File Manager" , 89, 108, 598, 469) ; 
InitialWindow (3 , " Program Manager" ,36,26, 545 , 333 ) ; 



LeftDblPress(249,121) ; 

WindowRc v { " Pt " ) ; 

AppWait(1.21) ; 
WindowRcv ( "CoCwAcSf Pt" ) ; 

CurrentWindow { "Employees ",44,44,636, 408 ) , 

Think<2.31) ; 

LeftButtonPress (62, 78) ; 



AppWait(0.22) ; 

WindowRcv ( "SfAcSfDwDwAcSfSf SfPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPt" ) ; 
WindowRcv ( "PtPtPtPtPtPtPtPtPtPt" ) ; 

CurrentWindow ( " Program Manager ",36,26,545,333); 

SysKeyPress (VK_MENU) ; 

Type("fr") ; 

AppWait(0.06) ; 

WindowRcv ( "CoCwCwCwCwC^X^CwCwSfAcPt " ) ; 

CurrentWindow { "Run" ,72, 77, 450, 238); 

Type( "c:\\acct\\acct A M" ) ; 
WindowRcv ( "CwaACwCwCwCwCw" ) ; 



( continued on following page ...) 



EMPOWER/CS-Vl.0.1 



2-8 

Copynghl PERFORMIX, Inc. © 1995 



User's Guide— Script Development 



Openenv ( ORACLE , VERS IONV6V7 ) , 




UsernametLOGl, "scott/ tiger @SUT H ) ; 


Password {LOG 1 , " " } ; 




Logon ( ORACLE , LOGl ) ; 




WindowRcv { " SfAcSf Sf Sf DwPt " ) , 




CurrentWindow ( "Program Manager" , 36, 26, 545, 333) ; 


Open {LOGl, CURD ; 




AppWait(4.84) ; 




WindowRcv ( "AcSf Pt" ) ; 




CurrentWindow ( "Accounts ",147,66,533,360); 


But tonPush ( w Payable ",267,213); 


AppWait(O.OS) ; 




WindowRcv ( M Sf PtCwCwCwCwCwCwCwCwCwCwCwCwCw'' ) ; 


Begintimer ( "Accounts_Payable M ) ; 


Dbset (CUR1 , DEFER, TRUE) ; 




Parse (CUR1, M SELECT ID, FIRST__NAME, LAST_NAME, ADDRES S_L INE_1 , ADDRESS_LINE_2 , 


ADDRESS_LINE_3 , PHONE_NUMBER, FAX_NUMBER, COMM_PAID_YTD , ACCOUNT_BALANCE , COMMENTS 


FROM CUSTOMERS " ) ; 




DescribeAlKCURl, 1, 12); 




Dbset (CUR1,MAXARRSIZE, 64) , 




Define{CURl, *1\ STRING, 40); 


Define (CUR1, "2", CHAR, 21) 




Define{CURl, "3", CHAR, 21) 




Define{CURl, n 4*, CHAR, 21) 




Define(CURl, "5", CHAR, 21) 




Define (CUR1, "6", CHAR, 21) 




Define {CUR1, "1\ CHAR, 16) 




Define (CUR1, M 8", CHAR, 16) 




Define(CURl, "9", STRING, 40); 


Define(CURl, ' "10", STRING, 40); 


Define (CUR1, "11", CHAR, 241); 


Exec{CURl) ; 






( continued on following page . . . ) 
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Dbset(CURl, FETCHSIZE, 64); 
Fetch (CURD ; 

whi 1 e ( Ge tNex tRow { CUR1 ) I =NOMOREROWS ) ; 
End timer (Ac count s_Payable) ; 



Begintimer ( "Accounts" ) ; 
Commit (LOG1) ; 



WindowRcvt "PtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPt" ) ; 

Close (CUR1) ; 
Logoff {LOGD ; 
Closenv (ORACLE) ; 

Endtimer ( "Accounts " ) ,- 

Endscenario ( " script 1 " ) ; 



2.4.2 Cscc 

After the script file has been transferred to the UNIX driver, you should compile 
the script into a machine language version. The Cscc tool compiles the script which 
can be executed at the command line. Because the script is a C language program, 
additional C language statements can be added to enhance the script. In the 
following example, we will compile the script file examplel.c into an executable 
binary: 

$ cscc scriptl 

The script now can be executed from the command line: 
$ scriptl 
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2.43 Mix 



Mix emulates an actual multi-user environment by executing multiple scripts after 
they are compiled by Cscc. A script table and, optionally, a command file specify the 
number of users to emulate, the name of the script or scripts each user will 
execute, delay times between the start of each script, and the termination condition 
of the test. Each script that executes produces a log file used for preparing 
statistical reports. 

In the following examples, suppose you have created four scripts. Your mix table, 
tablel, could look like the following: 



userl, query logl 

user2, update log2 

user3, accounts log3 

user4 r customer log4 



With Mix, these scripts can be executed in a multi-user test 



$ mix 

Mix: EMPOWER/CS VI . 0 . 0 , Serial#R000 00-000 , Copyright PERFORMIX, Inc. 
1988-95 

mix> use tablel 
mix> start all 
[userl] started 
[user2] started 
[user3] started 
[user4] started 

mix> userl terminated (3/4) running 
user2 terminated (2/4) running 
user3 terminated (1/4) running 
user4 terminated (0/4) running 

mix> quit 
$ 
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2.4.4 Reports 

Generating performance reports from one or more executed scripts is 
accomplished in two steps. First, you must use the Extract tool which parses each 
script s log file and records response time information in a set of flat ASCII files. 

$ extract logl.l log2.1 log3.1 log4 . 1 

The Report tool then uses these ASCII files to produce statistical reports that 
describe response time and system throughput (Note: You also may generate 
reports from your own statistical or graphics programs.) Report will generate an 
EMPOWER/CS standard report similar to the following: 













$ report 








EMPOWER Standard Report 






Date: 


Fri Jan 27 14:49:14 1995 




Start time: 


14:42:42 






Stop time: 


14:43:23 






Duration: 


00:00:41 






Mix: 


4 users 






Unit: 


seconds 






Scenario 


Total Finish Thruput 


Median Average Minimum Maximum Std-Dev 




query- 


1 1 0.02 


31.26 31.26 31.26 31.26 0.00 




update 


1 1 0.02 


22.07 22.07 22.07 22.07 0.00 




accounts 


1 1 0.02 


30.95 30.95 30.95 30.95 0.00 




customer 


1 1 0.02 


22.18 22.18 22.18 22.18 0.00 




Overall 


4 4 0.10 


26.56 26.62 22.07 31.26 4.49 




Function 


Total Finish Thruput 


Median Average Minimum Maximum Std-Dev 




logoutl 


2 2 0.05 


4.35 4.35 4.33 4.36 0.01 







2.4.5 Draw 

Draw accepts one or more EMPOWER/CS reports to produce bar charts that depict 
relationships among performance results. These relationships can summarize a 
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single multi-user test or a series of multi-user tests in which each test contained a 
different user level or system configuration. The following example is a typical 
EMPOWER/CS bar chart 



Scenario Response Time 



Start time 
Stop time 
Duration 
Mix 

Input file 



14:42:42 
14:43:23 
00:00:41 
4 users 
report . STD 



Legend: 

* - Average 



32.5 +- 



R 30.0 + 
e 
s 

P 
o 

n 27.5 +■ 
s 



T 

i 25.0 + 
m 
e 



22.5 +- 



20.0 + * *- 



Scenario 





Scenario 


Response Time 


ID 


Description 


Average 


A 


query- 


31.26 


B 


update 


22.07 


C 


accounts 


30.95 


D 


customer 


22.18 
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2.4.6 Monitor 

Monitor displays critical user information on your UNIX script driver during multi- 
user emulations. Information is listed in logically grouped views that can be sorted 
on any field in the view. With this tool, you can monitor response times, control 
script execution, track and correct script errors and timeouts, and view test 
progress. You also can identify and debug problem scripts, verify system load, and 
take a "snapshot" of user activity during a system bottleneck. Commands are 
provided to suspend, resume, or kill executing scripts during the multi-user test 



Fri Jan 27 14:42:58 

View 1 of 7 Script 1 of 4 



EMPOWER/CS MONITOR VI . 0 (c) PERFORMIX, Inc. 1995 

Running Scriptld Sorting ^ Interval 5 



Scriptld 
userOOl 
user002 



_Script State 



LastEvent 



CurrentWindow 



query bpush ><ButtonPushxButtonPushxButtonPush> Employee Records 

update appwt ButtonPress>c : \acct\acct^M<ButtonPush> Acct Application 

user003 accounts appwt nPressxLef tButtonPress>c : \acct\acct A M Accounting 

user004 customer type <Lef tButtonPressxLef tButtonPress>c : \ Run 



2.4.7 Global Variables 

The Global Variables tool, EMPOWER/GV, provides advanced control over multi- 
user emulations by creating and controlling global variables that are shared among 
executing scripts. Global variables can be defined to direct scripts to terminate 
gracefully when they run an indefinite process. They also may be used to 
synchronize the execution of multiple scripts. Elements of EMPOWER/GV include 
various commands and functions that control access to variables; read, update, or 
test values of variables; and control shared memory segments. 
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3.0 Installation 

EMPOWER/CS was designed to operate in an environment in which the SUT can 
not distinguish between actual PC users and the UNIX script driver. The PC, UNIX 
script driver, and SUT must be connected along the same communication network. 
The EMPOWER/CS software does not affect communication between the user PC 
and the SUT as it captures their activity. 

Before a Capture session begins, the PC will run a licensing check with the UNIX 
driver to verify execution of Capture. If the PC can not communicate with the UNIX 
machine, you will not be able to execute Capture. The PC must also be linked to the 
UNIX script driver so that it may drive the PC during script execution in Display 
mode. 

If the PC can not communicate with both the UNIX driver and the SUT, then 
EMPOWER/CS can not capture client/server activity. If the UNIX driver and the 
SUT can not communicate, then the UNIX driver can not execute a multi-user 
emulation. 

The Capture, Display, and Tools elements of EMPOWER/CS run on a Microsoft 
Windows PC and the remaining EMPOWER/CS software runs on the UNIX script 
driver. So that the PC can communicate with the UNIX script driver for the licensing 
check and for script execution in Display mode, the PC must have installed the 
dynamic link library winsock.dll Version LI. The PC application communicates 
with the database according to how you have set up your client/server 
environment Both the PC and the UNIX driver must have the appropriate database 
libraries installed to communicate with the database on the server. 

When a script is executed, the PC no longer is required because the UNIX driver 
replaces the PC user to interact with the SUT. However, if you choose to observe a 
script as it progresses, you can activate the "Display" option for the script to display 
captured user activity on the PC 
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3.1 The EMPOWER/CS Environment 

The following equipment is required to capture user activity with EMPOWER/CS: 

□ One IBM-compatible PC with keyboard, mouse, and monitor running Microsoft 
Windows software, winsock.dll Version 1.1, database libraries that assist with 
communicating with the SUT, and the EMPOWER/CS components Capture, Display, 
and Tools 

□ The UNIX script driver machine with database libraries that provide comparable 
communication with the SUT and EMPOWER/CS software 

□ The database server 

□ One communications network connecting the PC, the UNIX script driver, and the 
database server 



3.2 Installing the User PC, the UNIX Script Driver, and the 

Database Server 

You should follow the appropriate installation procedures described in the owners 
manuals for the user PC, the UNIX script driver, and the database server. 



3.3 Installing the EMPOWER/CS Software 

You must complete two installations to fully operate EMPOWER/CS. The 
EMPOWER/CS components (Capture, Display, and Tools) must be installed on the 
PC and the remaining EMPOWER/CS software must be installed on the UNIX script 
driver. 
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33.1 Installing EMPOWER/CS on the UNIX Script Driver 

The EMPOWER/CS software package is installed into four directories. The bin 
directory contains binary programs, the lib directory contains libraries of compiled 
functions, the h directory contains header files, and the install directory contains 
installation files. 

You will need at least 15 megabytes of free disk space on your UNIX script driver 
to install and run EMPOWER/CS. You also will need additional space to store scripts 
and log files. The UNIX script driver must run a version of the UNIX operating 
system, the appropriate database libraries, and a C language compiler. 

To install the software, follow these steps: 

Create a directory for the EMPOWER/CS software. 

The simplest directory to create is /usr/empower. Some customer sites 
create a separate EMPOWER/CS account and install the software in the 
home directory of that account. If you create an EMPOWER/CS 
account, we suggest you call it empower in the event PERFORMIX must 
access the account for future maintenance or upgrades. 

The remaining instructions are based on installing EMPOWER/CS in 
/ us r / empower. 

Log in as the user who will own the EMPOWER/CS software. 
(Note: This user typically is empower.) 

Change to the directory where the software will be stored: 

$ cd /usr/empower 

Step 4: Insert the EMPOWER/CS distribution tape into a tape drive. You must 
either use the default tape drive or determine the /dev name of the 
tape drive you will use. 
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Step 5: Use the tar command to read in the tape. Some examples of tar 
commands are listed below: 

$ tar xov 

$ tar xovf /dev/rSA/qtapel 

Step 6: Change to the install directory and execute the eminstall 

command. You will be instructed to contact PERFORMIX and provide 
your machine identification code to obtain your installation password, 
for example: 

$ cd Install 
$ ./eminstall 

You will receive a message similar to the following: 



Please print the " . . /Install/machineid" file, note your 
name, fax number, and phone number, and fax it to 
Performix at 703-893-1939. 

We'll generate your installation password and fax it back 
as soon as possible. When you get your installation 
password, re-run eminstall. 

If you are unable to send a fax, please call Performix at 
703-448-6606. 



This message is stored in the machineid file which can be printed and 
faxed to PERFORMIX. You will be given a special password consisting 
of all alphabetical characters, for example, jklmnopqrs- 

ABCDEFGHLMNOPWXYZ. 
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Execute eminstall again and enter the installation password when 
prompted. The interaction should look similar to the following example: 



$ . /eminstall 


Installation 


password : JKLMNOPQRS -ABCDEFGHLMNOPWXYZ 


installing . . 


/ 1 ib/ empower cs . a . . . 


installing . . 


/ 1 ib/ empower csm. a. . . 


installing . . 


/bin/cscc. . . 


installing . . 


/bin/ draw. . . 


installing . . 


/bin/extract . . . 


installing . . 


/bin/gv_cmds . . . 


installing . . 


/bin/mix. . . 


installing . . 


/bin/mon. . . 


installing . . 


/bin/report. . . 



Step 7: If your system supports ranlib(l) (usually on BSD versions of UNIX), 
run ranlib against the EMPOWER/CS function libraries: 

$ ranlib lib/*. a 

The software installation is now complete for your UNIX script driver. You must 
now proceed to the next section to configure the UNIX script driver for 
EMPOWER/CS. 



33.2 Configuring the (INIX Driver for EMPOWER/CS 

Step 1: Log in to your system as the user who will use EMPOWER/CS. (/Vote- 
Running EMPOWER/CS or any other software package as root is not 
advisable.) 

Step 2: Define your shell environment variable empower to be the directory in 
which EMPOWER/CS was installed. 
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For example, if you are a C-sheil user, add the following line to the 
.cshrc file in your home directory: 

setenv EMPOWER / us r /empower 

If you are a Bourne-shell user, add the following line to the .profile 
file in your home directory: 

EMPOWER=/usr /empower; export EMPOWER 

Step 3: Add $ empower/ bin to your path. This step is accomplished by 

modifying the path statement in the .cshrc or .profile file in your 
home directory. You must modify your path to be below the setting of 
the empower environment variable. 

If you are a C-shell user, the path setting statement in your .cshrc file 
should be: 

set path = { . /bin /usr/bin $ EMPOWER /bin ) 

If you are a Bourne-shell user, the path setting statement in your 
.profile file should be: 

PATH=. : /bin: /usr/bin : $EMPOWER/bin 

Step 4: Log out of your system and then log back in. This step causes your 
environment variables and path to be set correctly. 



33.3 Installing EMPOWER/CS on the PC 

When you install the EMPOWER/CS components onto your PC, EMPOWER/CS 
libraries and directories are created automatically. By default, the EMPOWER/CS 
libraries are placed under the directory empower which also includes a bin 
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directory of binary programs. If you wish to place these files under a directory 
other than empower, specify a new directory during installation when prompted. 

You will need at least five megabytes of free disk space on your PC to install and 
run EMPOWER/CS. You also will need additional space to store scripts and log 
files. The PC must include the libraries of the database server, the DOS operating 
system, and Version 3.1 of Microsoft Windows. 

To install the EMPOWER/CS components onto your PC, follow these steps: 

Insert the Installation diskette into your disk drive. 

From the DOS prompt, switch to the appropriate disk drive. Execute the 
DOS install command from the correct disk drive by typing the name of 
the drive and csinstal (Example: a: \csinstal). If Microsoft 
Windows is already running, in the Program Manager window, choose 
Run from the File Menu. In this window, type the name of the drive and 
the install command (Example: a:\csinstal) and select OK. 

Follow the instructions that appear on screen for the remainder of the 
installation. 



3.4 Before Starting Capture 

Before you can Capture with the EMPOWER/CS software, a licensing verification 
must occur between the PC and the UNIX script driver. This licensing check will 
occur when you start Capture. 

Before starting Capture, you must run eld on the UNIX machine. You should start 
eld as super-user (root) and you must set and export the empower environment 
variable to the local directory that contains the EMPOWER/CS software. 
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Example: 



# EMPOWER= /us r/ empower 

# export EMPOWER 

# eld 



You now should be able to use the EMPOWER/CS software. Confirm the 
installation by starting Microsoft Windows on your PC and activating the 
EMPOWER/CS window and then the Capture icon. 

The software installation and setup are now complete. Remove the EMPOWER/CS 
tape from the tape drive and store it, with the EMPOWER/CS diskette, in a secure 
location. 
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4.0 Capture 

The EMPOWER/CS Capture tool is used to capture communications between a 
user PC and the SUT to build executable scripts. After you complete a Capture 
session, the assembled scripts can be executed from a UNIX script driver to 
emulate numerous users of the client/server system. 

When activated, Capture records all interactions between the PC and SUT including 
mouse and keyboard strokes, SQL requests to the SUT, and data transmitted to the 
PC. Automatically, this information is stored in a script file with a " . c" extension in a 
specified directory on your PC to be used for subsequent script execution. The . c 
extension implies that the file is recorded in C language syntax for later C 
compilation and execution. Refer to Sections 5 and 6 of this manual for more 
information on script compilation and execution. 

The following script segment illustrates the types of user functions and database 
traffic contained in a script. This script contains such captured activity as user 
entries, connection and logging on to the database, and execution of a query: 



AppWait(0.22) ; 

WindowRcv ( "SfAcSfDwDwAcSf Sf Sf PtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPf } ; 
WindowRcv { " PtPtPtPtPtPtPtPtPtPt " } ; 

CurrentWindowC Program Manager" , 36 ,26, 545, 333) ; 

SysKeyPress (VK_MENU) ; 

Type( N fr M ) ; 

AppWait(0.06) ; 

WindowRcv ( "CoCwCwCwCwCwCwCwCwSfAcPf ) ; 

CurrentWindow( "Run" , 72 , 77 , 450 , 238) ; 

Type(*c:\\acct\\acct"M") ; 
WindowRcv { " CwCwCwCwCwCwCw H ) ; 

Openenv {ORACLE , VERSI0NV6V7 ) ; 

(continued on following page . . .) 



EMPOWER/CS-Vl.0.1 



4-1 

Copyright PERFORMIX, Inc. © 1995 



User's Guide— Script Development 





Username(LOGl, "scott/ tiger@SUT" ) ; 




Password (LOGl, " "} ; 






Logon ( ORACLE , LOGl ) ; 






WindowRcv( "SfAcSfSfSfDwPt" ) ; 






Curr en tWindow ( " Program Manager ",36,26,545,333); 




Open (LOGl, CURD ; 






AppWait{4.84) ; 






WindowRcv( "AcSfPt" ) ; 






CurrentWindow ( "Accounts " , 147 , 66 , 533 , 360) ; 




ButtonPush ( 11 Payable w , 267 , 2 13 ) ; 




AppWait{0.05) ; 






WindowRcv ( " Sf PtC^CvCwCwCwCwCw^^ ) ; 




Begintimer ( H Accounts_Payable" ) ; 


yQ 


Dbs e t { CURl , DEFER, TRUE ) ; 






Parse (CUR1, " SELECT ID, FIRST_NAME, LAST_NAME, ADDRESS_LINE_1 , ADDRESS_LINE_2 , 




ADDRESS_LINE_3 , PHONE_NUMBER , FAX_NUMBER , COMM_PAID_YTD , ACCOUOT_BALANCE , COMMENTS 




FROM CUSTOMERS " ) ; 






DescribeAlKCURl, 1, 12); 






Dbset (CUR1,MAXARRSIZE, 64) ; 


y 


DefinetCURl, "1", STRING, 40); 




Define (CURl, "2", CHAR, 21) 






Define (CURl, H 3\ CHAR, 21) 






Define (CURl, "4 M , CHAR, 21) 






DefinetCURl, M 5\ CHAR, 21) 




is*? 


DefinetCURl, "6", CHAR, 21) 






DefinetCURl, "7", CHAR, 16) 






DefinetCURl, "8\ CHAR, 16) 






DefinetCURl, M 9\ STRING, 40); 




DefinetCURl, "10", STRING, 40); 




DefinetCURl, "11", CHAR, 241); 




Exec (CURl) ; 






Dbset (CURl, FETCHSIZE, 64); 






Fetch (CURl) ; 






whi le ( GetNextRow ( CURl ) ! =NOMOREROWS ) ; 




Endtimer( "Account s_Payable) ; 
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For a more detailed explanation of script content, please refer to Section 7 Script 
Content and Enhancement of this manual. 



4.1 Suggestions for Executing Capture 

If you plan to execute EMPOWER/CS scripts in Display mode, you must ensure 
that the steps captured in the application to be tested are repeatable, meaning that 
all captured mouse activity can be precisely repeated by the UNIX script driver 
machine during script execution. Capturing mouse clicks in each activated window 
is not recommended because the recorded mouse locations, i.e., xy coordinates on 
screen, may not apply during script execution. For instance, windows do not always 
open in the same location each time they are activated. During script execution in 
Display mode, the recorded xy coordinates in the mouse event functions could be 
invalid and cause the script to malfunction by not activating the correct locations to 
activate applications or commands. Maximizing windows will ensure that all mouse 
actions are repeatable because the window will cover the entire screen allowing 
recorded xy coordinates to remain the same in Display mode. 

Since keyboard presses and commands are more precise, we recommend that you 
use the keyboard as much as possible to activate windows, commands, or 
applications. Some keyboard capabilities are listed below: 



O Alt + Space Bar to open system menus 

O Alt + F to open file menus 

O Control + F4 to close program windows 

O Arrow keys to move through menus or among icons 

Refer to your MS Windows user guide for full instructions on using the keyboard 
to control your Windows desktop. 
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4.2 Executing Capture 

Capture is executed from Microsoft Windows on your PC. 

If Windows is not currently running on your PC, from the DOS prompt, type "win" 
and press return. 

The Windows desktop and Program Manager window will open containing various 
program group icons. Activate the EMPOWER/CS program group. 

Example: 



Program Manager 



File Options Window Help 



A<*o 








e « ^ 

6.2. © 








A <£_ © 











Applications StartUp 



PC/TCP 
DosApps 



Empower/OS 



Main 



Ave 




A v © 




§4^ 

AVO 




d ± .A 
AVO_ 







Accessories 



Games 



Microsoft PC/TCP wIN STALL 3.3 
— nnnr ^ » * — 
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The following EMPOWER/CS window will open which includes three program-item 
icons: Capture, Display, and Tools. 

Select the Capture icon: 



Program Manager 



File Options Window Help 



a « .a 

A.<SO 



StartUp 



PC 
D( 



e ± a 




< 









Accessories 



Empov/er/CS 



Capture 



UfUUflilO 

Display 



Tools 



Before you may begin Capture, the PC must set up an initial communication or 
licensing check with the UNIX script driver. If this initial contact can not be made, 
you will not be able to execute Capture and will receive sn error. Note: You must 
be sure to run eld as root on the UNIX machine before starting Capture on the PC. 
(Refer to Section 333 of this manual). 



If the licensing check was successful, the following Capture command window will 
open prompting you to enter a script name: 
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Capture 



File Help 




This Capture window includes two items in the Menu Ban File and Help. The File 
menu includes Options..., Directory..., and Exit The Help Menu (located in all the 
EMPOWER/CS windows) includes About... for listing EMPOWER/CS copyright 
information. 



The About Capture screen is shown below: 



MOTS 



Capture 

Empower/CS Capture vl.O 
© Performix, Inc. 1994 
Serial #: ROOOOO-000 



[OK] 



Before you enter a script name to begin capturing, you may wish to change some 
of the Capture menu options. Under the File Menu, select Options.... 
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4.2.1 Options 



When you choose Options..., the following Options window will open: 



Capture Options 



Think Threshold 



0 



F12 



Bring to front with 

View script □ 
•Transfer script after capture 



□ Database traffic only 

□ Insert timers 



Database... 



Host 
Username 

Password 
Remote Directory 



indy 



john 



******** 



Jtemp 



License Daemon 



foo 



OK 



Cancel 



These Options are described more fully in subsequent sections. 
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When you change an option and select OK, a verification window will appear asking 
you to confirm changes. 

Example: 



Options 



Save options? 
Cancel 



If you select OK again, another Window will appear stating that the Options have' 
been saved. Select OK to return to the Capture command window. 



Capture 



Options saved 
I [QKj 
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To ignore any changes you made, select Cancel. A verification window will appear 
stating that the changes will be lost Select OK to return to the Capture command 
window. 



Example: 



Options 



Changes will be lost 





OK! 




Cancel 



In the Options window, you may change any of the Capture options during your 
Capture session, except Database traffic only and the Database . . . Chooser. 



4.2.1.1 Think Threshold 

This option specifies the number of seconds that EMPOWER/CS will wait before 
inserting a Think () function into the script ,c file. (Refer to Section 7 Script 
Content and Enhancement for a more detailed explanation of think time functions.) 
For example, suppose you specify a Think threshold of 2 seconds. If no activity is 
captured after two seconds, EMPOWER/CS will insert a think time function of at 
least two seconds and the time elapsed until the next action occurs. 

You may specify any two digit number of seconds for this option. 
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4.2.1.2 Bring to Front with 

Once you have begun capturing activity, the Capture window will minimize into the 
lower left corner of the Windows desktop. (Note: If you have maximized the 
window of your test application, you will not be able to see the Capture icon.) By 
simply pressing a hot key, you can bring the Capture command window up, 
temporarily halting the session. 

With this option, you may specify one of the function keys (Fl, F2, etc) as a hot 
key. The default hot key is F1Z 

Example: 



Capture Options 



Think Threshold 



0 



Bring to front with 


F12 


± 




F10 




View script 


F11 




Transfer script after ca 


F12 





Host 



indy 



□ Database traffic only 

□ Insert timers 



Database. 



Note: You should specify a function key that will not be used in your application. 



4.2.1.3 View Script 

Selecting the View script option allows you to look at the script file as you Capture. 
During Capture, the View script window appears on screen showing the script .c 
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file as user and database activity is captured. This option will help to familiarize you 
with the script functions that relate to activity you capture. 

The following example demonstrates a View script window during Capture: 



Dberror(CONTINUE); 
Unset(NOTIFY); 

Beginscenariofexl"); 



f* What to do on Database errors */ 

f* Don't display warnings. I'll use Mon to find them */ 



4,2.1.4 Database Traffic Only 

If you select this option, only database traffic will be captured into the script, which 
makes your script more compact 

Database traffic includes such functions as open(), Parse (), (),Exec(), 
Fetch ( ), etc. which are inserted into the script when the client application interacts 
with the database. Mo user interactions, such as mouse button presses or Type { ) 
functions, are inserted into the script file. However, the amount of time taken to 
type characters or move the mouse will be included in the Think ( ) times that are 
recorded into the script. (Refer to Section 7 Script Content and Enhancement for a 
full description of these script functions.) 

If you specify this option, your script can be executed only in Non-Display mode. 



4.2.1.5 Insert Timer 

If you specify this option, Begintimer ( ) and Endtimer ( ) functions are inserted 
automatically into the script during Capture to mark database traffic. These 
functions will be inserted around database traffic that occurs between two user 
events. A user event such as pressing the Return key on the keyboard or 
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activating a pushbutton on screen may initiate database activity. The parameters to 
these functions will designate the last user event before database activity began. 

When the script is exectued, the Begintimer ( ) and Endtimer { ) functions will be 
time stamped in the script's log file for the Report tool to measure response time of 
the database activity. 

The following example demonstrates Begintimer {) and Endtimer () captured 
into a script file around a database query. Notice the user event captured as the 
functions' parameters was a ButtonPush{ ) event, when a user pressed the button 

"Payable": 



CurrentWindow {"Accounts" , 147, 66, 533, 360) ; 
ButtonPush( "Payable" ,267,213) ; 

AppWait (0.05) ; 

WindowRcv ( " Sf PtCwCwCwCwCwCwCwCwCwCwCwCwCw" ) ; 
Begintimer ( " Accounts_Payable" ) ; 
Dbset (CUR1 , DEFER, TRUE) ; 

Parse (CUR1, " SELECT ID, FIRST_NAME, LAST_NAME, ADDRESS_LINE_1 , 
ADDRESS_LINE_2, ADDRESS_LINE_3 , PHONE_NUMBER , FAX_NUMBER, COMM_PAID_YTD , 
ACCOUNT_BALANCE, COMMENTS FROM CUSTOMERS " ) ; 

DescribeAll (CUR1, 1, 12); 



Endtimer ( " Accounts_Payable" ) ; 



4.2.1.6 Database Chooser 

This option allows you to choose the database on the server that you will access 
during the Capture session. 
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A window similar to the following opens when you select this option: 



Database 



Oracle 



Sybase 



OK 



Cancel 



4.21.7 Transfer Script after Capture 

Once a script is captured, it must be transferred to the UNIX machine to be 
executed. If you select this option, your script .c file will be transferred automatically 
when you stop Capture. 

You must specify the following information for the PC to connect to the UNIX script 
driver and transfer the script file. 
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Example: 



-Transfer script after capture 



Host 
Username 

Password 



foo 



john 



A A A A A A 



Remote Directory /tmp| 



License Daemon 



indy 



OK 



Cancel 



In the Options window, enter the Host name (the name of the UNIX driver), the 
Username, the Password (the user's password, if any), and the Remote Directory 
(the path on the UNIX driver where you wish to transfer the script). 



If large amounts of data (i.e., images, large text files, etc.) are input to the database 
during Capture, such data is inserted into separate data files. These data files will be 
transferred to the UNIX driver machine with the script if the Transfer script after 
capture option is selected. The data files are associated to the script with a . d 
extension' and a number that is incremented for each file. For example, two data 
files created for the script, scriptl .c f would be named as follows: 



scriptl.dOl 
scriptl. d02 



If you prefer, you may transfer the script file manually with the Transfer tool under 
EMPOWER/CS Tools. Refer to Section 8 EMPOWER/CS Tools for more 
information on manual script transfer. 
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4.2.1.8 License Daemon 

if you specified a license daemon during EMPOWER/CS installation, this option 
lists the name of that license daemon. If you need to change or specify a license 
daemon machine (which is the UNIX script driver used for your emulation), you 
must enter the new name in this dialog box. 



4.2-2 Directory 

You may use this File Menu option to store scripts in a different directory on your 
PC 

Select Directory... under the File Menu. The following window will open 
designating the directory and disk drive where your scripts currently are being 
saved. 
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Directory 



Directories: 
c:\ 



O arcade 
Q bmDs 
CDdash 
Q dcaD 
Q demo 
Hdos 
Q emDower 
CD f Itsim5 
Qqs 



Drives: 



c: 



OK 



Cancel 



Network. 



Select from the Directory list the name of the directory or the disk drive to which 
you wish to change, and then select OK or Cancel as appropriate. 



4.2.3 Capturing Application Activity into a Script File 

In the Capture command window, enter the script name you are capturing. The 
script file name can include up to eight alphanumeric and underscore characters. If 
you enter more than eight characters or other character types, Capture will ignore 
them. During Capture, the script file is stored automatically in the specified 
directory in an ASCII file with a ".c" extension. 
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Example: 




When you have entered a script name, select Start 



If the script name you enter already exists, the following warning message will 
appear, asking if you wish to overwrite the existing file. Select OK or Cancel as 
appropriate. 




Upon selecting Start, the Capture window will minimize, or iconify, into the lower 
left comer of the desktop signifying that all subsequent user and database actions 
are being captured 

Now, you should open the application to be tested Refer to your application's user 
guide for full operating instructions. Remember to maximize your application 
window upon activation if possible and use keyboard commands instead of the 
mouse during your Capture session. 
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Please note that user activities are captured only from Windows standard 
applications. For example, EMPOWER/CS does not capture user activity from DOS 
applications running under Windows. 

At this time, you should perform the application activity you wish to test 



4.2.4 Comments, Functions, and Timers 

You can add timers functions, or comments, to your script file while you are 
capturing by activating the Capture icon. The following Capture command window 
will open. When the Capture window appears on screen, all capturing activity halts 
temporarily. 



File Help 



Capture 



Timer 
Function 
Comment 



Resume 



Begin 



Begin 



Insert 



Stop 



Inserting timers allows you to mark specific activity for response time 
measurement. C language functions most commonly are used to help define a 
script segment for looping purposes. They also are used to define a common 
interaction, such as logging onto or off of the SUT You should add comments to 
your script file to add context to the script for editing purposes. 
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4.2.4.1 Inserting Timers 



You can manually insert the functions Begintimer () and EndtimerO into your 
script to mark activity for response time measurement. You must enter the name of 
the timer in the Timer dialog box of the Capture window and select Begin. Select 
the Resume button to return to the Capture state to capture the activity you wish to 
measure. 



When you have captured all needed activity, activate the Capture icon to open the 
Capture window. Select the End button next to the Timer dialog box. The following 
window will appear to verify the end of the timer 




If you have finished inserting the timer, choose OK in this verification window. 
Your desktop then will return to the Capture state. 



4.2.4.2 Inserting Functions 

To create a C function, enter the name of the function in the Function dialog box 
and select Begin. Select the Resume button to return to the Capture state to capture 
the function activity. 

After you have completed capturing the function, activate the Capture window and 
select the End pushbutton next to the Function dialog box. 
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The following window will appear verifying the end of the function: 




If you have finished inserting the function, choose OK in this verification window. 
Your desktop then will return to the Capture state. 



When you create a function, a function call is inserted within the script and the 
actual function (that includes captured activity) is placed at the end of the script file. 
Automatically, the EMPOWER/CS functions Beginf unction ( ) and 
Endf unction ( ) are inserted around the captured function. After a script is 
executed, Beginf unction ( ) and Endf unction ( ) cause time stamps to be 
recorded in a log file which is used to create detailed response time reports. 
Marking functions in such a- way allows you to measure reponse time for specific 
activities in your application. Refer to Section 6.4 The Log File in this manual and to 
Section 33 of theMulti-User Testing manual for more information on time stamps. 

The following example demonstrates a function logout ( ) that was captured into 
the script file, scriptl.c: 
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logout { ) 
{ 

Beginsource ( " scr iptl . c " ) ; 
Beginf unction { " logout" ) ; 



Think{4.66) ; 



Lef tButtonPress (202,99); 
Lef tButtonPress <236, 244) ; 



AppWait(0.28) ; 
WindowRcv { " ScDwAc " ) ; 

CurrentWindow ( "Capture - scriptl " , 21 , 690 , 57 , 726 ) ; 



Commit (LOG1) ; 



WindowRcv ( " Pt " ) ; 
Logof f (LOG1) ; 
CI os env (ORACLE) ; 



Endf unction ( " logout " ) ; 

Ends our ce ( ) ; 

) 



Beginsource ( ) and EndsourceO statements are automatically inserted around 
Beginf unction( ) and Endf unction { ) to prepare the function as a source file. 
For instance, during a multi-user emulation, you may wish to break the function out 
of the script into its own separate file that could be called by multiple scripts 
performing the same function. Modular script design is achieved by storing one or 
more functions in separate script source files. The C language cc compiler allows 
functions stored in these files to be compiled separately and then linked to the 
primary script file. Beginsource ( ) and Endsource ( ) specify the source file used 
during script execution. 
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EMPOWER/CS organizes functions as described in this section to format the script 
as a C language program. Refer to Section 52.3 Modular Script Design for a more 
detailed description of C function formatting. 



4.2.43 Comments 

You may insert a C comment into your script by entering the comment in the 
Comment dialog box of the Capture window and selecting Insert 

Select the Resume or Stop pushbutton as appropriate when you have entered your 
comment If you select Resume, your desktop will return to the Capture state. 



4.2.5 Completing Your Capture Session 

After you complete the application activity to be tested, close the application. 

Activate the Capture icon to halt the Capture session. The Capture window will 
appear. 

If you are ready to end the Capture session, select the Stop, button or Exit from the 
File menu. The following window will appear verifying that Capture has stopped: 
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If you did not connect to the SUT to capture database traffic during your Capture 
session, the following warning message will appear as soon as you stop Capture. 



Warning 



No database traffic captured 



!QKj 



If you chose the automatic transfer option, your script will transfer automatically to 
the UNIX script driver after OK is selected in the Capture Stopped window. A 
window similar to the following appears that shows the progress of the file transfer 



Transfer 



Attempting to connect to 'indy' 



0% 

Cancel 
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If the PC is unable to connect to the UNIX driver, a message window similar to the 
following will appear 



Transfer 



Unable to connect to 'too' 



0% 

okT 



If the script .c file already exists on the UNIX script driver upon a successful 
transfer, the following window will come up asking you to overwrite the existing 
script .c file. Choose OK or Cancel as appropriate: 



Warning 



(J^ Script 'exl.c' exists on "may, overwrite? 





OK! 




Cancel 



If you did not select the automatic transfer option, you may transfer the script 
manually using the EMPOWER/CS Transfer Tool (see Section 8.0 EMPOWER/CS 
Tools) or a third party File Transfer Protocol (FTP) software. 

The Capture session is now complete. At this point, you can begin to capture 
another script or you can close Capture by selecting "Exit" from the File Menu. 
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If you choose Exit, you now are ready to compile your script(s) with Cscc on the 
UNIX script driver. Cscc is the EMPOWER/CS tool that compiles your scripts into 
machine language binaries for execution, if you wish to edit your script .c file, you 
should do so with a system editor such as vi after the script file has been 
transferred to the UNIX script driver. Refer to Section 7.0 Script Content and 
Enhancement for information on editing your scripts. 
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5.0 Cscc 

The EMPOWER/CS tool, Cscc, reads and compiles script files, translating them into 
machine language form. After compilation, the script can be executed from the 
UNIX driver machine for multi-user testing eliminating the need for multiple PCs. 
Script execution is accomplished in two steps: The script first must be compiled 
and then the compiled script is executed. This approach allows C language 
statements to be embedded in the script file to enhance control over script 
execution. 



5.1 Cscc Syntax 

Script compilation with Cscc begins with the cscc command. The syntax of the 
cscc command is given in the following usage message which you can access by 
entering cscc with a hyphen (-) parameter. 

$ cscc - 



EMPOWER/CS VI 
Usage : 



Options : 



Notes : 



0.1, Serial#R00OOO-00O, Copyright PERFORMIX, Inc. 1988-95 
cscc [-EFOacghsvm] [-o ofile] script ... 



-E 
-F 
-O 
-a 
-c 

-g 

-h 
-s 
-v 
-m 
-o 



Preprocesses the script and writes C to stdout 
Inserts function declaration (implies -c option) 
Optimize script binary 

afile Create an archive (.a file) from the named files 

Compile but do not link (creates .o file) 
Includes symbol table in script binary for debuggers 
Excludes help information from the script binary 
Prevents strip of script binary 
Print verbose cc command line 
Excludes Monitor code from script binary 

ofile Name output binary 



Before running CSCC, set the environment variable EMPOWER to the 
directory that contains the EMPOWER software. 
Set the environment variable E_C FLAGS to any additional cc 
compile options you want. 
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5.2 Cscc Environment Variables 

Cscc uses several environment variables. The EMPOWER/CS variable must be set 
to the name of the directory containing the EMPOWER/CS software before you 
can execute Cscc. 

Example: 

$ setenv EMPOWER / us r/ empower 

The EMPOWER/CS directory contains four sub-directories: bin, lib, h, and 
install. Cscc will search the lib and h directories for files needed during script 
compilation. If you have not set the EMPOWER/CS variable, Cscc will search the 
current directory for the files it needs and produce an error message similar to the 
following: 

can't find empowerm.h 

Cscc permits you to use a temporary directory other than the current directory for 
C compilations. Set e__tmpdir equal to the name of the temporary directory. 

Example: 

$ setenv E_TMPDIR "/tmp" 

Also before you can execute Cscc, certain environment variables must be set to 
specify the databases being used The environment variable e_databases must be 
set to designate which database with which you are going to compile. Valid choices 
for Oracle and Sybase databases are 0RACLE7, sybase4, or sybaseio. Note: If you 
are not sure which version of Sybase was used during Capture, you can look in 
your .c file for the OpenenvO function. The second parameter will list the 
appropriate version. 
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If necessary, this environment variable can be set to more than one database. 
However, you should only specify the database(s) you used during the Capture 
session. 

Example: 

$ setenv E_DATABASES ORACLE7 

With each e_databases environment variable you must set the Oracle or Sybase 
environment variables. 

If compiling with an Oracle database, set the environment variable oracle_home to 
the path where Oracle resides on the server. 

Example: 

$ setenv ORACLE_HOME /usr/oracle 

If compiling with a Sybase database, set the Sybase environment variable to the 
appropriate path. 

Example: 

$ setenv SYBASE /usr/sybase 

You also can pass flags when invoking the C compiler by defining an environment 
variable e_cflags and setting the variable equal to your compilation flags. The 
flags will be inserted after the cc command and before the file name. 

If you require additional libraries during the load phase of the C compilation, define 
the e_libs environment variable equal to the names of the libraries. 

Example: 

$ setenv E_LIBS "-la" 
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5.3 Compiling with Cscc 

To compile a script, you must enter the cscc command with the name of the 
source script (Note: You do not need to specify \ c " in the script file name 
because Cscc automatically searches for a file with this extension.) 

Example: 



$ cscc examplel 

Cscc: EMPOWER/CS VI . 0 . 1 , Serial#R000 00- 00 0 , Copyright PERFORMIX, Inc 
1988-95 

cc -s -o examplel ./cscc7086.c /usr/local/lib/* . a 



Cscc will look for the specified script file in the current directory. If you have saved 
the script file in a different directory, you can specify the path of the directory as 
part of the file name specification. 

$ cscc /usr/empower/scripts/examplel 

During script compilation with Cscc, the source script is converted and placed in a 
temporary file in the current directory. Then, the C compiler is invoked to compile 
this temporary -file. During the load phase of compilation, a special library of 
EMPOWER/ CS functions is included Once the compilation is complete and the 
executable file has been created, the temporary file is removed automatically and 
the executable file remains in the current directory. 

Cscc creates an executable file called examplel (with no extension) which can be 
executed by typing this file name at the command line. 



53.1 Specifying the Binary Name with -o 

By default, Cscc creates a binary version of the script with the same name as the 
script file but without the .c extension. If you want to save the binary with a 
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different name, you can use the -o option of the cscc command to specify the 
desired name. 

In the following example, the created executable script will be named databasel 
instead of query . c: 

$ cscc -o databasel query. c 



5.3.2 Preprocessing the Source Script with -E 

Before a script can be executed as a C language program, it must be preprocessed 
to include C function formatting (e.g., braces, functions, etc) in the source script file. 
By default, the cscc command automatically preprocesses the source script file. 
Also, if you capture functions during your Capture session, this C function 
formatting is inserted into the script file automatically. 

If you choose only to preprocess the script file without compiling it, you should use 
the -e option of the cscc command. Entering the -e option of the cscc command 
will convert and write the script source file to the standard output. You can display 
this converted file on screen for review or save it to a C program file for editing 
and later compilation. 

When Cscc is invoked on a preprocessed file, the main() C function will indicate 
to Cscc that no preprocessing is necessary. When Cscc compiles such a file, the 
library of EMPOWER/CS functions will be included. 

The following example shows preprocessing of the script source file examplel.c: 
$ cscc -E examplel 

If you prefer to save the converted file to a C program file, specify the name of the 
new file as part of the cscc command, as follows: 
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$ cscc -E examplel>newscript . c 
The file newscript.c can then be compiled with Cscc: 



$ cscc newscript 

Cscc: EMPOWER/CS VI . 0 . 1 , Serial#ROOOOO-000 , Copyright PERFORMIX I 
1988-95 

cc -s -o newscript newscript.c /usr/local/lib/ * . a 



5.33 Modular Script Design 

Since EMPOWER/CS scripts are C language programs, defining a common 
interaction in a C language function often is useful. This allows a script to include a 
function call rather than the complete set of script entries for activities that you 
want to be repeated within the script. For example, the following script starts with 
the Empowercs { ) function. The Empowercs ( ) function is similar to main ( ) in a 
normal C language program. This function calls the function, functionl ( ) , which 
is located later in the script 



EmpowerCS ( argc , ar gv ) 
int argc; 



{ 



char 



*argv; 



Thinkuni f orm ( 1 , 2.5); 
Timeout (300, EXIT) ; 
Unset (NOTIFY) ; 

Beginscenario ( "scriptl" ) ; 

InitialWindow{0, "Desktop" , 0, 0, 1024, 768) ; 
InitialWindowd, "Program Manager" ,830,186, 73, 605) ; 
InitialWindow{2 , "Accounting" , 413 , 679 , 1029 , 771 ) ; 



AppWait (0 .06) ; 
WindowRcv { "CwPtPt " ) 



(continued on following page ... J 



EMPOWER/ CS-V1.0.1 



5-6 

Copyright PERFORMIX, Inc. © 1 995 



User's Guide— Script Development 



Lef tButtonPress (457, 617) ; 

WindowRcv( " DwCoSf CwCwCwCwCwCwCwCwCwCwSf AcSzPt " ) ; 
CurrentWindow( "Run" , 429, 491, 880, 764) ; 
Type ( :c:\\acct\\acct A M" ) ; 

functionl { ) ; 



CurrentWindow ( "Capture - scriptl " , 21 , 690 , 57 , 726 , "Min" ) ; 
Commit (LOG1) 

Close (CUR1) ; 

WindowRcv ( " Pt " ) ; 
Logoff (LOG1) ; 
Closenv(ORACLE) ; 

Endscenario ( " scriptl n ) ; 

} 

functionl ( ) 
{ 

Beginsource ( " scriptl " ) ; 
Beginf unction ( M functionl " ) ; 

AppWait{0.22) ; 

WindowRcv ( " CwCwCwCwCwCwCwCw " ) ; 
Openenv (ORACLE, VERSIONV6V7) ; 

Username(LOGl, " scott / tiger@SUT" ) ; 
Password (LOG1, " " ) ; 
Logon { ORACLE f LOG1 ) ; 

Open (LOG1, CUR1) ; 

WindowRcv ( "AcSf M ) ; 

CurrentWindow { "Accounting Application" , 189 , 82 , 685 , 449 ) ; 

Endf unction ( " functionl " ) ; 
Ends our ce ( ) ; 

} 
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The function syntax can be inserted manually or may result from inserting a 
function during Capture. (See Section 4.2.4.2 Inserting Functions.) 

Your script also can access functions that are stored in other script files. Modular 
script design is achieved by storing one or more functions in separate script 
source files. The C language cc compiler allows functions stored in these files to be 
compiled separately and then linked 

You must use the -c option of the cscc command to create object files (with an ".o" 
extension) for each compiled script. 

Examples: 

2 $ cscc -c fund 

$ cscc -c func2 
ri $ cscc -c func3 

i| For a script to access these functions, a function call must be inserted within the 

script and the object files must be linked with the source script. This is 
y. accomplished by compiling the script source file and listing the object files as 

p parameters of the cscc command, as shown below: 

01 $ cscc scriptl funcl.o func2.o func3.o 

In the above examples, three separate functions are stored in the script source files 
fund . c, f unc2 . c, and f unc3 . c. Each is compiled separately and then linked to 
the source script file, scriptl. c. 

Individual object files may be stored and used by other scripts or included in an 
EMPOWER/CS library. 

When the -c option of the cscc command is used, the function stored in a 
separate file must include standard C language function formatting (e.g., braces, 
functions, etc.). 
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If a script is compiled from multiple source files, each source file must be specified 
as a source file by including Beginsource { ) and Endsource ( ) statements. When 
editing your script, you should insert the Beginsource ( ) function at the entry 
point of the source file, typically just before the first executable statement in each 
function. You should insert the Endsource { ) function at the exit point of the file, 
typically just after the last executable statement in each function. 

The following example script segment demonstrates a typical source file: 



logonl ( ) 
{ 

Beginsource { " logonl " ) ; 
AppWait (0.17) ; 

WindowRcv ( "Sf PtCwCwCwCwCwCwCw" } ; 
Openenv (ORACLE, VERS I0NV6V7) ; 

Us e r name (LOG 1, " scott/ tiger@SUT" ) ; 
Pas sword (LOG1, " " ) ; 
Logon ( ORACLE , LOG1); 

WindowRcv { " Sf AcSfDwPtPtPtPtPtPt " ) ; 

CurrentWindow( 11 Accounting" , 413 , 679 , 1029 , 771 ) ; 

Open(LOGl,CURl) ; 

WindowRcv ( " AcSf " ) ; 

CurrentWindow( "Accounting Application ",189 , 82 , 685 , 449 ) ; 

Endsource ( ) ; 
} 



Note: If you define C functions during your Capture session, Beginsource ( ) and 
Endsource () are placed around Beginf unction ( ) and Endf unction ( ) 
statements in the event you wish to break the function out later into a separate 
source file. 
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53.4 Extending Modular Script Compilation with -F 

The -F option of the cscc command extends the capabilities of modular script 
compilation to handle functions that do not include standard C function formatting. 
This option places the required formatting into the script automatically. 

For example, elements of the logonl { ) function may be contained in the following 
script file called logonl. c: 



Beginsource { " logonl " ) ; 
AppWait (0.17) ; 

WindowRcv{ " Sf PtCwCwCwCwCwCwCw" } ; 
Openenv (ORACLE, VERSI0NV6V7) ; 

Username(LOGl, "scott/tiger@SUT" ) ; 
Password ( LOG1 , " " ) ; 
Logon ( ORACLE , L0G1 ) ; 

WindowRcv( " Sf AcSf DwPtPtPtPtPtPt " ) ; 

CurrentWindow ( "Accounting" , 413 , 679 , 102 9 , 771 ) ; 

Open(LOGl,CURl) ; 

Endsource ( ) ; 



To compile this file into the object file logonl . o, use the -f option: 
$ cscc -F logonl 

Cscc adds the function definition logically to the source file and compiles it into the 
object file logonl . o. The -f option may not be used if the function is required to 
accept arguments. 
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5.3.5 Automatic Creation of Function Archives 

EMPOWER/CS can create archive and function libraries automatically with the -a 
option of cscc. This option is used as follows: 

$ cscc -a logonl funcl func2 

The -a option is followed by a list of script file names to be included in the archive. 
If a ".o" file exists for the given script file, the \o" file also will be added to the 
archive. If a M .o" file does not exist, Cscc will search for a ".c" file with the 
provided name. If a \c M file is found, it automatically will be compiled with the -c 
option , and the resulting ".o" file will be included in the archive. 

The name of the archive will be the first script name given, with a ",a" extension. 
The above example would create an archive file called logonl. a, which would 
include the files login. o, funcl. o, and func2 .o. 

The e_libs environment variable must then be set to include the archive file. 
Future execution of Cscc will include the new archive. Set the e_libs environment 
variable as follows: 

For Bourne shell users: 

$ E„LIBS=logonl.a; export E_LIBS 
For C Shell users: 

$ setenv E_LIBS logonl. a 

When the script is compiled with Cscc, the archive will be included in the compiler 
command line. 
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5.3,6 Optimizing and Stripping the Script Binary 

Cscc invokes the standard C language compiler "cc H . By default, Cscc strips (does 
not include) the symbol table from the binary and does not optimize the binary. You 
can change these defaults with the -o, -s, and -g options of the cscc command. 

The -o option of cscc specifies that the resulting script object code is optimized. 
However, since a script is primarily a series of function calls that can not be 
optimized the -o option has little effect and slows Cscc operation. 

Stripping the symbol table for a script makes it smaller; therefore, executing it 
requires less memory. However, you can specify that the symbol table is not 
stripped (is included) in the binary by using the -s option of cscc which invokes 
the -s option of the "cc" compiler. 

If problems occur during script execution, you may want to run a system debugger, 
such as dbx. System debuggers require that the symbol table is included in the 
executable script and that the file is not optimized. The -g option of the cscc 
command invokes the C compiler's -g option to include the symbol table and 
prevent optimization. This option, described in the manual for the cc compiler, will 
allow the resulting executable file to be used in a system debugger. 

An executable script file created with the -g option will be rather large and will 
require a large amount of memory to execute. Therefore, using -g is not 
recommended for scripts executed during a sizable multi-user emulation. 



5.3.7 Excluding Help Information from the Script Binary 

By default, Cscc includes help information in the executable version of the script it 
creates. This help information is shown in the Syntax help screen in Section 6.1. 



EMPOWER/CS-Vl.O.1 



5-12 

Copyright PERFORMIX. Inc. © 1995 



User's Guide— Script Development 



By using the -h option of the cscc command, you may compile the script to 
exclude help information from the executable file: 

$ cscc -h example30 

The resulting executable script will be smaller and require a bit less memory to 
execute. 

If you try to display help information for a script that was compiled with the -h 
option, the following error message will result: 



$ example 3 0 

error: example30: no help available. recompile without the -h option. 



5.3,8 Excluding Monitor Code 

By default, Monitor code is included in the executable script file after it has been 
compiled with Cscc An executable script file with Monitor code is somewhat larger 
requiring more resources to run than a file without the code. 

If you want to compile your script without Monitor code and therefore not use the 
Monitor tool, enter the -m option of the cscc command as demonstrated below: 

$ cscc -m example 7 



53.9 The Compiler Command Line 

The -v option of the cscc command specifies that the entire compiler command 
be listed after a script is compiled. By default, EMPOWER/CS lists a condensed 
version of the compiler command that does not include all libraries and options. 
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An example of a default compilation follows: 



$ cscc scriptl 

EMPOWER/CS VI. 0.1, Serial#ROOOOO-000 , Copyright PERFORMIX, Inc. 
1988-95 

cc -s -o scriptl ./csccl7366.c /usr/local/lib/* . a 



An example using the -v option follows: 



$ cscc -v scriptl 

EMPOWER/CS VI. 0.1, Serial#R00 000-000 , Copyright PERFORMIX, Inc. 1988-95 

cc -s -L/opt/oracle/lib -cckr -I/usr/local/h -o scriptl . /csccl7377 . c 
/usr/local/lib/empowercsm.a /us r/ local/ lib/empowercsMON. a /usr/ 
local/lib/empowerGV.a /usr/local/lib/oralib. a /usr/local/ lib/sybs tub . a 
/usr/local/lib/syb4stub.a -locic /opt/oracle/lib/osntab . o -Isqlnet 
-lora -Isqlnet -lcv6 -lcore -Inlsrtl -lcore -lsocket -Insl -lm 



JJ 5.4 Cscc Compilation Messages 

O Cscc generates error messages under the following conditions: The script can not 

be read, the EMPOWER/CS environment variable is not defined properly, or the 
preprocessed version of the script can not be read 

The following error message is generated when the script can not be read or does 
not exist: 



$ cscc example 1 

Cscc: EMPOWER/ CS VI . 0 . 1 , Serial#R00000-000 , Copyright PERFORMIX , Inc 
1988-95 

cscc: can't open exaiuplel.c. 
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The following error message is generated when the EMPOWER/CS environment 
variable is not defined properly: 



$ cscc examplel 






Cscc: EMPOWER/CS 


VI . 0 . 1 , 


Serial#R00OOO-00O / Copyright PERFORMIX, Inc. 


1988-95 






cscc: can't find 


empower m 


.h 



If the printf () function is incorrectly included in a script as print (), the 
following error message is generated: 



Cscc: EMPOWER/CS VI . 0 . 1 , Serial#ROOOOO-000 , Copyright PERFORMIX, Inc 
1988-95 

cc -s -o examplel . /csccl0965\ c /usr /local/lib/ *. a 
Id: 

Unresolved: 
print 



If you run Cscc to create a binary file called examplel while a script called 
examplel executes, you will receive the following error 

Bus error ( coredump ) 

All other error messages displayed during Cscc execution are generated by the C 
compiler. Compiler error messages will indicate the line number in the script that 
caused the error. 

Example: 



$ cscc examplel 

Cscc: EMPOWER/CS VI. 0.1, Serial#R00000- 00 0 , Copyright PERFORMIX, Inc 
1988-95 

cc -s -o examplel . /csccl4137 . c /usr/local/ lib/ * . a 

cfe: Error: examplel . c : 48 : Missing ')' in macro instantiation 
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6.0 Script Execution 

Two methods are available for executing a script: Non-Display and Display modes. 
Non-Display mode executes what was captured between the PC and the SUT but 
involves only the UNIX script driver and the SUT. Display mode involves the PC, 
the UNIX driver, and the SUT and displays the captured client/server activity on 
the PC 

If you did not specify -h in the cscc command, you can access syntax help for a 
compiled script by entering the script executable name followed by a hyphen (-). 

Example: 



$ examplel - 

examplel: EMPOWER/CS VI. 0.0, Serial#R00000-000 , Copyright PERFORMIX, Inc. 

1988-95 

Usage : 

examplel [-d hostname] [-S scriptid] [log [argl arg2 . . .]] 
Options : 

-d hostname Displays script execution 

-S scriptid Changes scriptid from example30 if not run from MIX 

log Identifies the log file to be created 

argl arg2 . . . Identifies optional script arguments 

Notes: If a log is not specif iecV the log examplel . 1 will be created. 

If you specify " " as the log, no log will be created. 
You must specify a log if you want to specify arguments, 
argl is accessible as the variable argv[3] in the script. 



6.1 Non-Display Mode 

Executing a script in Non-Display mode requires only the UNIX script driver and 
the SUT. The script on the UNIX driver replaces the PC to interact with the SUT, 
and the SUT responds as if it is servicing requests from an actual PC. 
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Executing EMPOWER/CS scripts from the UNIX script driver allows you to set up 
multi-user emulations by duplicating scripts or combining and executing multiple 
scripts. Refer to the Multi-User Testing manual for detailed information on 
executing multi-user emulations with EMPOWER/CS. 

To execute a script in Non-Display mode, you must first compile it on the UNIX 
script driver with the cscc command. 

The script file created by Cscc is a binary executable file. Therefore, you can 
execute a compiled script in Non-Display mode by typing the name of the script 
(with no extension) at the command line with a series of options, listed in the 
syntax help screen above. 

To execute the script example30, type the following at the command line: 

$ example3 0 



6.2 Script Execution in Display Mode 

Since the UNIX script driver replaces the PC during script execution, you are not 
required to display emulated user activities during script execution. However, script 
development and debugging often are easier if you can see the emulated activity. 
Therefore, you can display captured user and database activity on one or more PCs 
as a script executes. Each PC that you wish to display to must have a network 
connection to the. UNIX script driver and to the SUT. 

In Display mode, script execution is initiated from the UNIX script driver. The UNIX 
driver directs the PC to replay captured user activity and to wait for data returned 
from the SUT. The PC replays the entire script interacting with the SUT as directed 
by the UNIX script driver. During script execution, all interaction occurs between 
the UNIX script driver and PC, and between the PC and the SUT. The SUT receives 
all PC transmissions and responds accordingly to the PC. 
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Before a script can be replayed, or executed, in Display mode, you must compile 
the script on the UNIX driver machine with the cscc command. 

You also must set up the PC to display the script If your Windows application is not 
already running, from DOS on the PC, type "win" to start MS Windows. 

When the Program Manager appears, select the EMPOWER/CS program group. 
Then, select the Display program-item icon: 






mm 



Capture 
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The following window will open that displays a cartoon PC "listening" for network 
connections from the UNIX script driver: 



Display 



File Help 



4l 



The UNIX driver must connect to the PC to execute the script and control the 
captured PC activity. On the UNIX script driver, enter the executable script name 
with the -d option and the name of the PC to which you are displaying. 

Example: 

$ scriptl -d vagrant 

Every user interaction that was captured between the PC and the SUT will execute 
on the PC. The UNIX driver directs the PC to activate windows, select buttons, enter 
queries, etc. as if a real user were using the PC. The PC in turn will interact with the 
SUT as it would if a real user were using it. The SUT will respond to the PC 
accordingly. 

The Display icon on the Windows screen will disappear during script execution and 
will return only when the script exits. 
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As soon as the script has completed execution, the computer cartoon will appear 
again "listening" for any other connections. If you have completed script execution 
in Display mode, simply select Stop in the Display window. 



63 Script Execution Options 

The options listed in the syntax help screen are described in the following sections. 



63.1 -d 

This option is used only for Display mode script execution. On the UNIX script 
driver, enter the executable script name with the -d option and the name of the PC 
to which you are displaying. 

Example: 

$ scriptl -d vagrant 

See Section 62 above for further Display mode instructions. 



63.2 Changing the Script ID 

When you execute a compiled script, a variable called scriptid is defined as the 
name of the script. If you execute a script called query 1, the variable scriptid 
would be given the value, queryl. 

With the -s option of the script execution command, you can change the value of 
scriptid. 
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Example: 

$ examplel -S example2 

The scriptid variable is used in Monitor and can be used within a script. If you 
are running a multi-user test that executes a single script several times 
simultaneously, you should change the Script ID for each instance of the script. The 
Script ID acts as an emulated user ID. 

Note: If you are using the Mix tool, you do not need to specify the -s option to 
execute a multi-user test. Mix inserts the -s option automatically by reading the 
Script ID from the Mix table. (Refer to the Multi-User Testing manual for more 
information on the Mix table.) 



6.33 Specifying a Log File 

When a script executes, a log file is created in the current directory on the UNIX 
driver. This log file contains all emulated user activity, SQL requests to the SUT, and 
all data returned to the PC. To calculate response times, this log file also includes 
time stamps for the time that such functions as Beginf unction () , 
Endf unction ( ) , Beginscenario ( ) , and Endscenario ( } were executed. 

If you do not specify a name for the log file in the script execution command, the 
log file will be given the same name as the script with a " . 1" extension. You do not 
need to include the 1" extension if you specify a log file name. 

Example: 

$ exaraple30 -d vagrant log 

When you specify a log file name, you can include a path name to save the file in a 
directory other than the current directory. 
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Example: 

$ example30 -d vagrant /user/empower/logs/logOOl 

You also can define the e_logdir environment variable to specify a directory for 
log files as shown below: 

In the Bourne shell: 

$ E_LOGDIR=/user/ empower /logs ; export E_LOGDIR 

In the C shell: 

$ aetenv K_LOGDIR "user /empower/ logs " 

If you do not wish to create a log file, specify the null string (* ) as part of the 
script execution command which is useful for performing demos when disk space 
is limited. If you do not create log files, you will not be able to obtain statistical 
information for your test. 

Example: 

$ example30 -d vagrant " " 



63.4 Specifying Arguments 

Arguments may be passed to the script during execution by specifying them in the 
script execution command. You must specify log file names prior to specifying 
arguments, even if you wish to use the default log file name. 
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Example: 

$ example 3 0 example3 0.1 john passOOl 

Refer to Section 7.3 of this manual for more information on script arguments. 



6.4 The Log File 

Executing EMPOWER/CS scripts results in the creation of a log file for each 
executed script. If a script is executed so that the created log file has the same 
name as an existing log file, the new log file will overwrite the existing one. If you 
are running a multi-user test, you must ensure .that each emulated user writes to a 
different log file. 

The log file contains copies of user entries, every EMPOWER/CS function 
entered, SQL requests to the SUT, data returned to the PC, and time stamps used 
for performance measurement Entries in the log file that correspond to lines in the 
script source file include the characters >>> followed by the line number of the 
corresponding script file entry. 

The following is an example EMPOWER/CS log file: 
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>>> 




Log: scriptl.l 


>>> 




Date: Fri Jan 20 10:03:02 1995 


>>> 




Command: script 1 -d ergy 


>>> 




Beginsource ( " scriptl " ) 


>>> 


4 


Typerate(5.00) 


>>> 


5 


Pointerrate(150. 00) 


>>> 


6 


Thinkunif orm{ 1 .000,2.500} 


>>> 


7 


Seed(28310) 


>>> 


8 


Timeout (300, CONTINUE) 


>>> 


9 


Dberror (CONTINUE) 


>>> 


10 


Unset (NOTIFY) 


>>> 


12 


Beginscenario ( "scriptl " ) 10:03:02.89 


>>> 


14 


InitialWindow(0, "Desktop" , 0 , 0 , 1024 , 768 ) 


>>> 


15 


InitialWindowfl, "Program Manager " , 943 , 162 , 186, 581) 


>» 


16 


InitialWindow (2 , "Accounting" , 413 , 679 , 1029 , 771 } 


>>> 


18 


LeftButtonPress (448, 692) 


>>> 


21 


AppWait (0.05) 


>>> 


22 


WindowRcv ( " CwPtPt " ) 


CwPtPt 






>>> 


24 


LeftButtonPress (459, 616) 


>>> 


26 


WindowRcv ( "DwCoSf CwCwCwCwCwCwCwCwCwCwSf AcSzPt " ) 


S f S f Ac P t DwC oCwCwCwCwCwCwCwCwC wCwS z 


>>> 


28 


CurrentWindow ( "Run" ,429, 491, 8 80,7 64) 


>>> 


30 


Think 1.923 


>>> 


33 


LeftButtonPress (470, 575) 


>>> 


35 


Type( "c: \acct\acct A M" ) 


>>> 


37 


AppWait (0.22) 


>>> 


38 


WindowRcv ( " CwCwC wCwCwCwCw " ) 


>>> 




Username (LOG1, " scott/ tiger@SUT" ) ; 


>>> 




Password (LOG1, " " ) ; 


>>> 




Logon (ORACLE, LOG1) ; 


CwCwCwCwCwCwCw 


>>> 


97 


Think 2.141 


>>> 


98 


ButtonPush( "Employee Records | Next " , 739 ,438) 


>>> 


99 


But tonPush ( " Employee Records | Next ",739,438) 






( continued on following page ...) 
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ButtonPush ( "Employee Records | Next" ,739,438) 
ButtonPush ( " Employee Records | Close" , 718 , 157 ) 
WindowRcv( "SfPtDwAcSf " ) 

CurrentWindow ( "Accounting Application" , 189 , 82 , 685 , 449 ) 
Think 1.069 

Lef tButtonDown(204 , 105) 
Lef tButtonUp (211, 241 ) 
AppWait (0.39) 
WindowRcv ( " ScDwAcSf " ) 

Commit (LOG1) ; ScDw 

CurrentWindow ( 11 Accounting" , 413, 679, 1029, 771) 
Close (CURD ; 
Logoff (LOG1) ; 
WindowRcv ("Pt H ) 

Endscenario { " scriptl " ) 10:04:20.11 
Ends our ce ( ) 



The UNIX script driver drives the PC, instructing it to activate buttons and keys, to 
draw windows, to enter data, etc. according to functions in the script. In the above 
script, those types of user interactions are marked with line numbers which refer- 
back to a particular line in the script .c file. Because this script was executed on the 
PC in Display mode, you will notice that some lines in the log file contain no 
numbers corresponding to lines in the source script 

When a script is executed in Display mode, database traffic is generated by the PC, 
not the UNIX script driver. This traffic is captured and sent to the UNIX driver to be 
logged in the log file, but because these database functions were not executed by 
the UNIX driver, they contain no line numbers. 

If the script had been executed in Non-Display mode from the UNIX driver, its log 
file would include line numbers with the database functions because the UNIX 
driver interacts with the SUT just as a PC would. An example follows: 
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>>> 


100 


>>> 


101 


>>> 


103 


Sf AcSfPtDw 


>>> 


105 


>>> 


107 


>>> 


109 


>>> 


110 


>>> 


113 


>>> 


114 


AcSf 




>>> 




>>> 


116 


>>> 




>>> 




»> 


125 


Pt 




>>> 


127 


>>> 
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>>> 




Log: scriptl.l 




>>> 




Date: Fri Jan 20 10:12:23 1995 




>>> 




Command: scriptl 




>>> 




Beginsource { " scriptl " ) 




>>> 


4 


Typerate{5.00) 




>>> 


5 


Pomterrate (150.00) 




>>> 


6 


Thinkuniformd .000, 2 . 500) 




>>> 


7 


Seed(28544) 




>>> 


8 


Timeout (300, CONTINUE ) 




>>> 


9 


Dberror ( CONTINUE ) 




>>> 


10 


Unset (NOTIFY) 




>>> 


12 


Beginscenario ( " scriptl" ) 10 : 12 : 23 . 94 




>>> 


14 


InitialWindow(0, "Desktop" , 0 , 0 , 1024 , 768 ) 


o 


>>> 


15 


InitialWindowd, "Program Manager" , 943 , 162 , 186 , 581) 




>>> 


16 


InitialWindow(2, "Accounting" , 413 , 679 , 1029 , 771 ) 




>>> 


18 


LeftButtonPress (448, 692) 


it% 


>>> 


21 


AppWait (0.05) 


SI 


>>> 


22 


WindowRcv( "CwPtPt" ) 




>>> 


24 


LeftButtonPress (459 , 616) 




>>> 


26 


WindowRcv{ "DwCoSf CwCwCwCv^wCwCwCwCwCwSf AcSzPt " ) 




>>> 


28 


Curr entWindow ( " Run" ,429,491,880,764, Nor ) 




>>> 


30 


Think 1.288 




>>> 


33 


LeftButtonPress (470, 575) 


r-~.-H 


>>> 


35 


Type { "c : \acct \acct A M" ) 


ry 


>>> 


37 


AppWait (0.22) 


yl 


>>> 


38 


WindowRcv( " CwCwCwCwCwCwCw " ) 


u 


>>> 


39 


Openenv(ORACLEl, V6|V7) 


y 


>>> 


41 


Username (LOG1, "scott/tigeresUT" ) 




>>> 


42 


Password (LOG1, " " ) 




>>> 
• ■ * 


43 


Logon ( ORACLE , LOG1 ) 




>>> 


97 


Think 2.02 6 




>>> 


98 


ButtonPush ( " Employee Records | Next ",739,438) 




>>> 


99 


ButtonPushf "Employee Records | Next " , 739, 43 8) 




>>> 


100 


ButtonPush ( "Employee Records [Next " f 739, 438) 




>>> 


101 


ButtonPush ( "Employee Records | Close" , 718, 157) 




>>> 


103 


WindowRcv( " Sf PtDwAcSf " ) 




>>> 


105 


CurrentWindow ( "Accounting Application" , 189 , 82 , 685, 449) 




>>> 


107 


Think 1.008 








( continued on following page ...) 
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> > > 


1 n q 
i u y 


T jts •£ ¥- Dn f- f- flm-rn ( 0 H A 1 fl^ \ 

us I ldu 1 1 onuown \ ^ u ^ , iu j j 




> >> 


1 1 n 






>>> 


113 


AppWait ( 0 . 39 ) 




>>> 


114 


WindowRcv ( " ScDwAcSf " ) 




>>> 


116 


CurrentWindow ( "Accounting" 


,413,679,1029,771) 


>>> 


118 


Commit (L0G1) 




>>> 


121 


Close (CUR1) 




>>> 


122 


Logoff (L0G1) 




>>> 


123 


Closenv{ ORACLE) 




>>> 


125 


WindowRcv { " Pt" ) 




>>> 


127 


Endscenario ( " scriptl" ) 10: 


12:55.53 


>>> 




Ends our ce ( ) 





6.5 What Comes Next? 

Now that you have learned the basic concepts for emulating captured activity by 
executing a script, you are ready to begin a multi-user emulation. However, before 
proceeding to the Multi-User Testing Manual, you may wish to edit or enhance 
your scripts to emulate more realistic loads on your client/server system. The 
following section, Script Content and Enhancement, discusses common script 
functions, methods for editing your scripts, and advanced emulation techniques that 
allow you to develop realistic scripts. 
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7.0 Script Content and Enhancement 

Because your script .c file is a C language program and contains EMPOWER/CS 
functions, it can be edited to provide additional control over script execution. This 
section describes EMPOWER/CS script functions, various methods for editing 
your scripts, and advanced techniques for developing sophisticated scripts. 

Because extensive use of C language statements in EMPOWER/CS scripts 
constitutes advanced load testing, we recommend that you become proficient with 
all EMPOWER/CS tools before applying the concepts presented in this section. 



7 .1 Script Content 



The following example is a typical EMPOWER/CS script (Note: Some content is 
left out for brevity): 



/* EMPOWER/ CS VI. 0.1 Remote Terminal Emulator Script */ 



Typerate ( 5 ) ; 
Pointerrate(150) ; 
Thinkunif orm (1,2.5); 
Seed(getpid{) ) ; 
Timeout (300, CONTINUE ) ; 
Dberror (CONTINUE) ; 
Unset (NOTIFY) ; 



/* Typing delay in CPS *7 
/* Pointerrate in PPS V 
/* Think delay */ 

/* Seed random -number* generator */ 

/* What to do if DB transaction takes too long */ 

/* What to do on Database errors */ 

/* Don't display warnings. I'll use Mon to find them */ 



Beginscenario ( " scriptl " ) 



InitialWindowtO, "Desktop" , 0, 0, 1024,768) ; 
InitialWindowd, "Program Manager" , 943, 162, 186, 581) ; 
InitialWindow(2 , "Accounting- , 413 , 679 , 1029 , 771) ; 

LeftButtonPress(448,692) ; 



AppWait{0.05) ; 
WindowRcv ( "CwPtPt " ) , 



( continued on following page . . . ) 
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LeftButtonPress(459,616) ; 



WindowRcv ( " DwCoS f CwCwCwCwCwCwCwCwO^OtfSf AcSzPt " ) ; 



CurrentWindowC'Run" , 429 , 491, 880, 764) ; 



Think{2.53) ; 



/* Clicked (Edit) */ 
LeftButtonPress(470, 575) ; 



Type { " c : \ \ acc t\\scct A M" ) ; 
AppWait(0.22) ; 

WindowRcv ( H CwCwCwCwCwCwCw a ) ; 
Openenv { ORACLE 1 , VERSIONV6V7 ) ; 

Username(LOGl, "scott/tigerGSUT*) ; 
Password (LOG1, "tiger" ) ; 
Logon ( ORACLE1 , LOG1 ) ; 



WindowRcv ( "SfAcSfDwPtPtPtPtPtPtPtPtPtPtPtPtPt ■ ) ; 



CurrentWindow( "Accounting" , 413 , 679, 1029, 771) ; 



Open { LOG 1, CURD ; 
WindowRcv ( M AcSf " ) ; 



CurrentWindow { "Accounting Application* 4 , 189, 82 , 685, 449) ; 



Think(4.89) ; 

ButtonPush ( "Accounting Application | Customers " , 343 , 288) ; 



AppWait(5.72) ; 

WindowRcv ( " Sf PtCwCwCwCwCwCwCwCwCwCwCwCwCw" ) ; 
Begintimer ( "Accounting Application_Customers" ) ; 
Dbset(CURl, DEFER, TRUE) ; 

Parse (CURl, " SELECT ID, FIRST_NAME, LAST_NAME, ADDRESS„LINE_1 , ADDRESS_LINE„2 , 
ADDRESS_LINE_3 , PHONE_NUMBER , FAX_NUMBER, COMM_PAID_YTD, ACCOUNT_BALANCE , COMMENTS 
FROM CUSTOMERS " ) ; 

DescribeAlHCURl, 1, 12); 

Dbset (CURl ,MAXARRSIZE, 64) ; 
Define (CURl, "1", STRING, 40); 
DefinetCURl, M 2\ CHAR, 21); 
Define (CURl, "3", CHAR, 21); 
Define(CURl, "4-, CHAR, 21); 

( continued on following page . . .) 
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Define (CURl, 
Def ine(CURl, 
Define {CURl, 
Define (CURl, 
Define (CURl, 
Define {CURl , 
Define {CURl, 
Exec (CURl); 



"5" , CHAR, 21) ; 
"6" , CHAR, 21) ; 
"7\ CHAR, 16) ; 
M 8 M , CHAR, 16) ; 
"9" , STRING, 40) ; 
"10" , STRING, 40) ; 
"11", CHAR, 241) ; 



DbsetfCURl, FETCHSIZE, 64); 
Fetch (CURD ; 

while (GetNextRow(CURl) !=NOMOREROWS) ; 
Endtimer ( 'Accounting Application__Customers H ) ; 



WindowRcvCAcSfSfPf) ; 



CurrentWindow(" Employee Records" , 73, 82,790, 506) ( 
Think (18. 13); 

ButtonPusht "Employee Records | Next" , 739 , 438) ; 



AppWait(2.57) ; 
WindowRcvCSfPt") ; 



Think(7.80) ; 
ButtonPush { "Employee 
ButtonPush { "Employee 
ButtonPush ( "Employee 
ButtonPush { "Employee 



Records (Next", 739, 438) ; 
Records | Next ",739, 438) ; 
Records |Next" , 739 , 438) ; 
Records | Close", 7 18 r 157) ; 



WindowRcv( "SfPtDwAcSf " ) ; 



CurrentWindow ( "Accounting Application" , 189 ,82,685, 449 ) ; 



Think (4. 23 ) ; 



LeftButtonDown(204,105) ; 
LeftButtonUp{211,241) ; 



AppWait<0.39) ; 
WindowRcv { " ScDwAcSf " ) ; 

CurrentWindow ( "Accounting" , 413, 679, 1029,771) ; 

Begintimer ( "Accounting" ) ; 
Commit (LOG1) ; 

( continued on following page . . .) 
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Close (CURD ; 
Logoff CL0G1) ; 
Closenv (ORACLED ; 

WindowRcv( "Pt M ) ; 

Endtimer ( "Accounting" ) ; 

Endscenario ( " scriptl * ) ; 



7.1.1 General Script Functions 

~=Sr; / 

Descriptions of general EMPOWER/CS script functions are presented in the 
following sections. 



7.1.1.1 Begin/End Functions 

EMPOWER/CS has three sets of "Begin" and "End M functions which mark the start 
and finish of scenarios and functions. These functions are Beginscenario ( ) , 
Endscenario ( ) , Beginf unction ( ) , Endf unction ( ) , Begintimer ( ) , and 
Endtimer ( ) . 

The parameter for each function is the name of the script section being defined 
Each "Begin" function must have a corresponding "End" function and the 
parameter used in each "Begin" function must match the name used in the "End" 
function. 

The Beginscenario () and Endscenario ( ) functions cause scenario time stamps 
to be recorded in the log file. These functions are inserted into the script ,c file 
automatically during Capture to mark the beginning of the script. Scenarios typically 
define large sections of emulated activity. Usually an entire script represents a 
scenario. 
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The Beginf unction ( ) and Endf unc t ion ( ) functions are inserted by the 
EMPOWER/CS user during Capture or during script editing to define specific 
activity as a C function. These functions cause function time stamps to be recorded 
in an executed script's log file which allows the Report tool to calculate response 
time statistics for the function. The Report tool will indicate the response time for 
executing the entire set of activities in the function. 

The BegintimerO and EndtimerO functions are inserted into the script 
automatically during Capture if the Insert Timer option is specified or manually by 
the EMPOWER/CS user. They are used to calculate response times for the 
activities they define. If Insert Timer is selected, BegintimerO and EndtimerO 
are placed around database traffic that occurs between two user events in the 
script. If Insert Timer is not selected, the user can insert these functions to specify 
activity to be measured in the script 



7.1.1.2 Typerate and Pointerrate 

A high fidelity emulation of PC user activity should include a simulation of the time 
required to type at the keyboard. EMPOWER/CS allows you to specify a typing 
speed, measured in characters per second, that is applied to all emulated keyboard 
activity. 

The Typerate O function sets the typing speed. During script execution, each 
time that the emulated user is supposed to be typing at the keyboard, the script will 
pause a length of time defined as the number of characters to be typed times the 
type rate specified For example, if the emulated user must type twelve characters 
and the type rate is specified as six characters per second (Typerate ( 6 ) ) then the 
script will pause two seconds when the emulated characters are to be "typed." 

The default function t Typerate (5) , is placed at the top of every script created by 
EMPOWER/CS, specifying a type rate of 5 characters per second. You may change 
this rate during script editing. If you specify a type rate of zero in the script 
(Typerate (0)), then no delay is used when the script emulates a user typing at the 
keyboard. 



EMPOWER/ CS-V1.0.1 



7- 5 



Copyright PERFORMIX. Inc © 1995 



User's Guide— Script Development 



EMPOWER/CS applies the type rate by inserting a delay between each emulated 
typed character listed in the Type ( ) function. For example, if the emulated type 
rate is five characters per second and five characters are to be sent to the SUT, 
EMPOWER/CS will pause 1 second between each character. 

The type delay is applied using UNIX system functions particular to your UNIX 
machine. Each delay technique may include some inaccuracy of up to 0.5 seconds. 
This inaccuracy over the course of a type-intensive script may affect the duration 
of script execution, the actual type rate, and ultimately, the accuracy of the 
performance statistics. 

EMPOWER/CS keeps track of the difference between the specified type rate and 
the actual type delay. This difference is known as typing drift Throughout script 
execution, EMPOWER/CS compensates for typing drift by adding to or reducing 
type delays as appropriate. 

Other supported delay methods on your UNIX machine are nsdelay, sleepdelay, 
pseudodelay, and selectdelay. nsdelay is accurate to 0.01 seconds. The 
sleepdelay method uses the sleep (2) system call, which is accurate only to 0.5 
seconds, pseudodelay allocates a pseudo port on the machine for delays. It is 
accurate to 0.1 seconds. If the machine runs out of pseudo ports, the delay is 
applied with sleepdelay. selectdelay, which is used for BSD systems, uses the 
select (2) system call and is accurate to 0.01 seconds. Although other delay 
methods are available, the most accurate delay method on your UNIX script driver 
is that used by EMPOWER/CS. 

An accurate representation of PC user activity also should include a simulation of 
the time required to move the mouse. EMPOWER/CS allows you to specify a 
speed for mouse movements, measured in mouse points per second, that is 
applied to all emulated mouse activity. 

The Pointerrate ( ) function specifies the points per second that the mouse 
pointer moves. During script execution, each time that the emulated user is 
supposed to move the mouse, the script will pause a length of time defined as the 
number of points moved times the pointer rate specified. For example, if the 
emulated user points the mouse to 120 locations and the pointer rate is specified as 
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60 points per second (Pointerrate{60)) then the script will pause for 2 seconds 
when the emulated mouse movements are executed. The pointer rate delay is 
similar to the concept of type rate delay as described above. 

The default function, Pointerrate(ioo), is placed at the top of every 
EMPOWER/ CS script, specifying a pointer rate of 100 points per second. You may 
change the default value during script editing. If you wish to use no pointer rate 
delay during your emulation, specify Pointerrate(O). 

During script execution, EMPOWER/CS applies the emulated pointer rate by 
inserting a delay between each point that the mouse should move. In Display mode, 
you will notice that the mouse pointer will pause during each pointer movement 
from one specified location on screen to the next 



7.1.1-3 Think Time Functions 

Think time functions insert pauses in script execution to emulate when a user 
pauses to think before continuing to interact with the PC These pauses are 
represented by the Think { ) , Thinkactual ( ) , Thinkconstant ( ) , Thinktne ( ) , 
and Thinkunif orm( ) script functions. The Think () function specifies when a 
pause should be inserted during script execution. Thinkactual O specifies that 
actual captured think times should be used. The other three functions define the 
length of the think delay by specifying a think time distribution. 

The Think ( } function, which may appear throughout the script, will cause the script 
to pause its execution according to the most recently defined think time 
distribution. 

During Capture, you may specify the number of seconds that EMPOWER/CS will 
wait before inserting a Think ( ) function into the script file. The Think ( ) function 
is inserted in the captured script file only after the specified time has elapsed. By 
default, if no activity is captured after two seconds, EMPOWER/CS will insert a 
think time function of at least two seconds and the time elapsed until the next 
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action occurs. The parameter of the Think {) function specifies the number of 
seconds elapsed. 

During script execution, Thinkactual ( ) tells the script to use values in the 
Think ( ) functions that were captured during your Capture session. The following 
example demonstrates using this function within a script. When you edit your 
script, insert Thinkactual ( ) as shown below: 



./* EMPOWER/CS VI. 0.1 Remote 


Terminal Emulator Script */ 






Typerate (5) ; 


/* 


Typing delay in CPS */ 






Pointerrate{150) ; 


/* 


Pointerrate in PPS */ 






Thinkactual ( ) ; 


/* 


Think delay */ 






Seed(getpid( ) ) ; 


/* 


Seed random number generator */ 






Timeout (300, CONTINUE) ; 


/* 


What to do if function takes too 


long 


*/ 


Dberror (CONTINUE) ; 


/* 


What to do on Database errors */ 






Unset (NOTIFY) ; 


/* 


Don't display warnings. I'll use 


Mon 


to find them */ 


Beginscenario ( " examplel " ) ; 








Think time distribution 


may 


be defined with any of these three 


think 


time 



functions: Thinkconstant ( ) , Thinktne { ) , and Thinkunif orm ( ) . Varying think 
time distribution throughout a script is common and, typically, each application will 
have its own think time distribution. These functions define a distribution of 
randomly chosen think time amounts and can be inserted more than once 
throughout the script file when editing your script Because the script was captured 
with think time values, a value must be specified in Think ( ) functions for script 
execution (even if the value is zero), regardless of the think time distribution. 

Thinkconstant { ) specifies that the think time is the same every time a Think ( ) 
function is encountered. The think time amount is specified by the parameter 
constant. The syntax is: 

Thinkconstant (constant) 
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Thinktne ( ) defines a truncated negative exponential distribution of think time 
amounts. The parameters specify the minimum, average, and maximum: 

Thinktne (min, avg, max) 

Thinkunif orm ( ) defines a uniform think time distribution. Think time amounts 
will be chosen so that they are evenly distributed between the amounts specified 
by the parameters min and max: 

Thinkunif onti{ min, max) 

Random number generation for EMPOWER/CS functions is provided by a random 
number generator internal to the EMPOWER/CS software. Random number 
generation is required for ' the EMPOWER/CS functions Range (), 
Thinkunif orm { ) , and Thinktne { ) . The EMPOWER/CS internal random number 
generator will provide consistent results for all UNIX platforms. 

If the same range parameters and seed value are provided for Ranged, 
Thinkunif orm ( ) , and Thinktne { ) , the same random number will be generated 
every time. To ensure unique random numbers, you should use the Seed() 
function to seed the random number generator uniquely for each user. The 
example script at the beginning of this section shows the use of the Seed{ } 
function where the process ID is used as a seed for the random number generator. 



7.1.1.4 Timeouts and Database Errors 

The Timeout ( ) function specifies how long EMPOWER/CS will wait to receive an 
expected response during script execution. When a matching response is not 
received in the specified time, the script is said to "time out." The Timeout () 
function specifies the length of time to wait before a timeout and the action to be 
taken when the script times out The syntax for the function is: 

Timeout (n, cond) 
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Similarly, the Dberror { ) function specifies the action to be taken if a database 
error occurs. The syntax is: 

Dberror (cond) 

The parameter n in the Timeout ( ) function is the number of seconds to wait 
before a timeout (an integer). The cond parameter in both Timeout {) and 
Dberror ( ) is the action to be taken at timeout or database error. This parameter 
can be either continue or exit or a user-defined function, continue specifies 
that script execution continues to the next function in the script and is generally the 
condition specified, exit halts script execution. 

The default functions, Timeout {300, CONTINUE) and Dberror (CONTINUE) , are 
placed at the top of every script created by EMPOWER/CS. During script 
execution, Timeout (300, continue) specifies that the script will wait 300 
seconds (five minutes) for the expected response, then continue. 
Dberror (continue) specifies that the script will continue if it enounters a 
database error. You can edit these functions and/or insert them throughout the 
script to suit your testing needs. 

The following conditions may cause timeouts or database errors to occur during 
script execution: 

O If a script times out and continues prematurely, receipt of the "late" response 
(meaning the response took longer than the specified 300 seconds) likely will throw 
script synchronization off, which could cause continual timeouts until the script 
exits. If your SUT is slow, you may need to increase the timeout value. 

O When multiple clients are accessing the SUT during script execution, responses to 
your script(s) or PC (in Display mode) could be delayed. 

O During script execution in Display mode, EMPOWER/CS waits for specific 
windowRcv( ) patterns. If the expected windowRcv ( ) patterns are not received in the 
specified time, a timeout will occur. 
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O The state of the SUT during script execution may not be identical to its state during 
Capture (e.g. ( if the script tries to delete a record in the database that already has 
been deleted) which could cause unexpected responses to be received by the script 
or PC 

O Processing a database function may take longer than the specified timeout time. 

Timeouts and database errors can be identified by observing script execution in 
Display Mode or Monitor and by inspecting the log file. The following example 
shows a portion of a log file containing a timeout. In this example, the script timed 
out on a windowRcv ( ) function and because the timeout condition was continue, 
the next script function was executed. 



»> 27 AppWait (0.05) 

»> 28 WindowRcv { "SfPtDwAcPtPtPtPtPtPtPtPtFtAcSf" ) 

S f P t Ac Ac S f P t DwP t 

»> Timeout 16:18:12.25 

>>> Needed: PtPtPtPtPtPtPt 

»> Buf fer:SfSfAcSf 

»> 30 CurrentWindow{ "Sample Application ",189 , 82 , 685 , 449 ) 

»> 32 Lef tButtonDown(213 / 105) 

»> 33 LeftButtonUp(212, 105) 



7.1.1.5 Set and (Inset 

To aid in creating sophisticated script files, various EMPOWER/CS options are 
available during script execution. The Set( ) and Unset { ) functions allow you to 
specify certain activities and settings for your emulation. These functions can be 
inserted or changed when you edit your script. 

Set ( ) turns on EMPOWER/CS options during script execution. Unset ( ) turns off 
EMPOWER/CS options during script execution. 
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Valid options are listed below: 



Option Description 

lcmd log miscellaneous commands 

flush flush SUT responses to the log that are detected after a pattern 

match in s windowRcv ( ) 

nobuf don't use buffered writes to the log file 

notify display a message when a timeout occurs, execution is 

suspended, or execution resumes 

bell ring the bell twice when a timeout occurs 

logging Enable logging 



7.1.1.6 Mouse Activity 

The following list shows all the functions used to emulate mouse button activity for 
the left, middle, or right mouse buttons during script execution: 

Lef tButtonDown(x, y) MiddleButtonDown (x, y) RightButtonDown (x, y) 
Lef tButtonUp (x, y) MiddleButtonUp (x,y) RightButtonUp (x , y) 

Lef tButtonPress (x,y) MiddleButtonPress (x,y) RightButtonPress (x,y) 
Lef tDblPress (x,y) MiddleDblPress (x,y) RightDblPress (x,y) 

These functions are inserted into the script .c file during Capture when the 
specified mouse activity is performed. 

The function parameters x,y indicate the xy coordinates of the mouse on screen at 
the time the mouse button was activated during Capture. 

The "ButtonDown" functions indicate when the specified button on the PC mouse 
was pressed down. 
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The "ButtonPress" functions indicate when the specified button on the PC mouse 
was pressed down and released. A ButtonPress event is inserted in the script when 
a ButtonDown and ButtonUp event do not contain other user events between them 
and the x,y coordinates are the same. 

The "ButtonUp" functions indicate when the specified button on the PC mouse was 
released. This function will be captured into the script file instead of a ButtonPress 
function if the x,y coordinates are different between two consecutive down/up 
mouse activities. 

The "DblPress" functions indicate that the user double-clicked a mouse button. 
During script execution, these functions emulate two consecutive presses and 
releases of the specified button. 

During script execution in Display mode, these functions are used to emulate the 
specified mouse activity. In Non-Display mode, the x,y coordinates are used to 
simulate moving the mouse by emulating a mouse pointer delay to the next x,y 
coordinates. 

Mouse button events may be edited in your script file, but because you change the 
activity from when it was captured, you run the risk of breaking the script. 

The following example script segment contains various mouse button activities: 



AppWait (5.21) ; 




WindowRcv( "Pt" ) ; 




LeftButtonDown(213, 111) ; 




AppWait (0.55) ; 




WindowRcv( "Pt" ) ; 




LeftButtonUp{222, 195) ; 






(continued on following page . . .) 
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AppWait (0.38) ; 
WindowRcv( "Pt" ) ; 

Lef tButtonDown(3 40, 216) ; 
Lef tButtonPress (333 , 219) 



AppWait (0 .17) ; 
WindowRcvCPt" ) ; 

Lef tButtonPress (350,202) ; 



7.L1.7 Keyboard Activity 

The following list shows the functions used to emulate keyboard activity during 
script execution: 

KeyPress (key) SysKeyPress (key) 

Key Down ( key ) Sy s Key Down ( key ) 

KeyUp ( key ) Sy s Key Up ( key ) 



The parameter key represents a Microsoft Windows virtual key code value. All 
possible virtual key code values are listed below: 



VK_TILDE 


VK_LAPPOST 


VK_UNDERSCORE 


VK_HYPHEN 


' VK_PLUS 


VK_EQUAL 


VK_LCURLY 


VK_LSQUARE 


VK_RCURLY 


VK_RSQUARE 


VK_C0L0N 


VK_SEMI 


VKJDQUOTES 


VK_SQUOTES 


VK_LTHAN 


VK_COMMA 


VK_GTHAN 


VK_PERIOD 


VK_QUESTION 


VK_SLASH 


VK_PIPE 


VK„BKSLASH 


VK_CANCEL 


VK_CLEAR 


VK_TAB 


VK_BACK 


VK_SHIFT 


VK_CONTROL 


VK_MENU 


VK_PAUSE 


VK.CAPITAL 


VK_ESCAPE 


VK_SPACE 
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VK_PRIOR 


VK_NEXT 


\7Y FTVTn 
v x\ HiiyiLJ 


VK_HOME 


VK_LEFT 


-V i\ U c 


VK_RIGHT 


VK DOWN 


VA.__bh*LhL X 


VK_EXECUTE 


VK SNAPSHOT 


\7"K" T TvT C tT D T< 


VKJDELETE 


VK HELP 


V J\_IN U rl r AD U 


VK_NUMPADI 


VK NUMPAD2 


VJ\_iNUrlrAD.5 


VK_NUMPAD4 


VK NT IMP ADS 


V i\_JN U JM FAD b 


VK_NUMPAD7 




VK_NUMPAD9 


VK_MULTIPLY 


VK ADD 


VK_S E P ARATOR 


VK„SUBTRACT 


VK" TYFr'TMZir 


VK_DIVIDE 


VK_F1 


VK 

v xv r z. 


VK_F3 


v js. r fi 


VK_F5 


VK_F6 


VK_F7 


VK_F8 


VK_F9 


VK_F10 


VK_F11 


VK_F12 


VK_F13 


VK_F14 


VK_F15 


VK_F16 


VK_F17 


VK_F18 


VK_F19 


VK_F20 


VK_F21 


VK_F22 


VK_F23 


VK_F24 


VK_NUMLOCK 


VK_SCROLL 





These functions are inserted into the script during Capture when the specified key 
activity is performed. 

The "KeyDown" functions indicate that a non-printable keyboard key on the PC was 
pressed down. 

A "KeyPress" function is translated into a KeyDown/Up sequence. A KeyPress 
function is captured into the script when no user events are contained within a 
KeyDown/Up pair. 

The "KeyUp" functions indicate that a non-printable keyboard key on the PC was 
released. 

The "SysKey" functions indicate that the keyboard activity included pressing the 
Alt key. "Sys" implies that the keystrokes are being sent to the System Menu of 
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the current window which is located under the icon in the top left corner of the 
window as shown below: 



Empower/CS 



Move 




Size 




Minimize 




Maximize 




Close 


Ctrl+F4 


Next 


Ctrl+F6 



Tools 



During script execution in Display mode, these functions are used to emulate the 
specified keyboard activity. In Non-Display mode, type rate is applied to these 
events and the script delays accordingly. 

Key events may be edited in your script file, but because you change the expected 
activity from when it was captured, you may break the script when it is executed. 

The following example demonstrates various keyboard and mouse activity in a 
script file: 



Beginscenario ( M example2 M ) ; 
Lef tButtonPress {188 , 381) ; 

WindowRcv ( "CwPtPtDwCoSf CwCwCwCwCwCwCwCwCwCwS f AcSzPt " ) ; 

(continued on following page . . .) 
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LeftButtonDown(193, 316) ; 
LeftButtonUp(193, 317) ; 

CurrentWindow ( "Run" , 189 , 82 , 685 , 449 ) ; 

AppWait (0.11) ; 

Type ( "c: WacctWcWacct^'" ) ; 
WindowRcv( "CwAcSfDwPt " ) ; 

CurrentWindow ("General Ledger", 234,99,704,520); 

AppWait (1.26) ; 

Sys Key Down (VK_MENU) ; 
SysKeyPress (VK_SPACE) ; 
SysKeyUp(VK_MENU) ; 

Type ( "scott^Itiger^IFOO^M" ) 



7.1.1.8 Type 

The Type ( ) function is recorded into a script file during Capture when keystrokes 
are entered from the keyboard. The parameter of the Type ( ) function may include 
the standard keyboard keys pressed (except for those defined as virtual key codes 
in Section 7.1.1.2) and the non-displayed key combinations defined below. Each key 
translates into a KeyDown/Up pair for the emulation. 

Non-displayed key combinations are shown in the parameter of the Type ( ) 
function using the standard UNIX technique in which the character " represents the 
Control key. Common control sequences captured into the Type ( ) function are 
listed below: 

~M Carriage Return 

Backspace 
"I Tab 

Delete 
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Note: You may notice that if you use the number pad or a symbol font during your 
Capture session, the numbers or symbols will not be captured into the Type( ) 
function. For instance, if you are using a symbol font where the "A" key represents 
"a", pressing this key will be captured as Type ("a"). To capture numerical 
characters, you should use those listed at the top of the standard keyboard. Only 
standard keyboard keys are captured into a script .c file. 

During script execution in Display mode, the Type ( ) function is used to emulate a 
user typing the specified keystrokes. In Non-Display mode, this function emulates 
a typing delay. 

Type strings are very easy to modify and can be edited to alter the keystrokes 
typed by an emulated user. For example, the following Type ( ) function is entered 
in a query: 

Type{ "13402"M" ) ; 
It can be modified to: 

Type("98704~M") ; 

The following example shows a portion of a script containing a Type { ) function in 
which the user entered a command during Capture to run an application: 



AppWait (0.11) ; 

Type("c:\\acct\\c\\acct A M" ) ; 
WindowRcv( "CwAcSf DwPt" ) ,- 

CurrentWindow( "General Ledger" ,189, 82, 685, 449); 



Note: If executing your script in Non-Display mode, any modifications you make 
to the Type ( ) function will not affect the data that is input to the database. It will 
only affect the amount of type delay to be emulated. If you do want different data to 
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be input to the database, you will need to change the corresponding Parse ( ) or 
Data ( ) statements. 



7.1.1.9 ButtonPush 

The ButtonPush () function is inserted into the script file during Capture to 
indicate that a specific button, a MS Windows pushbutton such as OK, Cancel, Yes, 
No, etc., was activated It is .used during script execution in Display mode to move 
the mouse to activate the specified pushbuttons. In Non-Display mode, this function 
simulates mouse movement as defined in the x , y parameters to allow for mouse 
pointer delay. 

The syntax of this function is: 

ButtonPush (str, x,y) ; 

The parameter str may be listed in a format similar to the following examples: 

ButtonPush ( " Program Manager | Run | OK ",226,99) ; 
ButtonPush ( "Tools | #cl | #c4" ,68,69); 
ButtonPush ( "OK" , 187, 201) ; 
ButtonPush ( "#02" , 299, 134) ; 

The format of the str parameter is designed so that EMPOWER/CS can easily 
locate the captured pushbutton during script execution in Display mode. This 
format is based on the MS Windows concept of a tree structure. 

The MS Windows tree structure is based on a heirarchy of windows where each 
window that is accessed from a primary, or parent, window is a child of that parent. 
The str parameter is pipe-delimited, and is listed right to left from child to parent 
window where the right-most item is the name of the pushbutton. If one of the 
windows or the pushbutton has no title, something like n #cl" will be listed to 
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indicate the window is a certain numbered child of the preceding parent window. 
EMPOWER/CS will be able to locate the specified pushbutton by following the 
heirarchy listed in the str parameter. 

In the first example listed above, ok is the name of the pushbutton that was 
activated. Run is the name of the window that contained this ok button, and Run was 
a child window of the parent window 'Program Manager. In the second example 
listed above, #c4 was the pushbutton activated and was the fourth child of the first 
child (#cl) of the Tools window. 

If the buttons parent window is the active or current window, only the button will 
be listed in the str parameter. In such a case, you may notice ButtonPushO 
functions similar to the following in your script file which will follow a 
CurrentWindow( ) function: 

If you wish to edit this function in your script file and need to determine a button's 
tree structure, you can use the Tree Tool under EMPOWER/CS Tools. See Section 
8.4 of this manual for more information on the Tree tool and the MS Windows tree 
structure. 

In the following example script segment, the user activated the ok pushbutton to 
open an application: 



CurrentWindow ( "Run" , 189 , 82, 685, 449) ; 
Type( H c: \ \acct\ \c\ \acct A M) ; 
ButtonPush ( "OK" , 354 , 153 } ; 



7.1.1.10 InitialWindow 

This EMPOWER/CS function is inserted into the script during Capture after the 
Beginscenario ( ) function. InitialWindow ( } records the state of your Windows 
desktop by listing all active program windows at the time the Capture session 
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began. Therefore, if multiple applications are open when you begin Capture, 
multiple initialwindow( ) functions will be listed in the script file. 

The following example demonstrates initialwindowf ) functions captured in a 
script file: 



Beginscenario ( 11 scr iptl " ) ; 

InitialWindow{0, "Desktop" , 0 , 0 , 1024 , 768) ; 
InitialWindowd, "Program Manager" ,989, 34, 232, 453); 
InitialWindow(2, " MS-DOS Prompt ",0,0, MAXWIDTH , MAXHEIGHT ) ; 



The first parameter of the initialwindow( ) function indicates the position of the 
program in the MS Windows task list. The program's position in the Windows task 
list is important for users who capture a script using "Fast-Tab" task switching. 
Position o is a reserved value; it is used to record the screen resolution during 
Capture and verify the resolution for script execution in Display mode. 

The second parameter identifies the title of the window. 

The next two numerical parameters indicate the x,y coordinates of the top left 
portion of the window on screen. Then, the next two parameters indicate the width 
and height of the window. If the width and height are both zero, the window is 
minimized. If the x,y coordinates are both zero, and width is maxwidth and height 
is maxheight, the window is maximized. If neither of these conditions apply, the 
window is in a normal state. 

During script execution in Display mode, initialwindowf ) attempts to locate the 
windows listed as parameters and place them in their captured positions. The 
function does not apply to Non-Display mode script execution. 

If the specified programs are not open at the time of script execution or if a 
window could not be moved to the specified position, the log file will record a 
warning but script execution will continue. Therefore, before you execute your 
script in Display mode, your desktop should have the same applications open as 
when you captured the script 
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You should not attempt to remove or edit this function in your script file because 
you would change the state of the Windows desktop from when it was captured, 
and, therefore, may break the script. 

Note: The first ini tiaiwindow ( ) function listed in the script indicates the 
resolution of the screen as the first xy parameters are 0,0. You will notice a task 
order of 0 specified in this first ini tiaiwindow ( ) function. The zero indicates to 
EMPOWER/CS to check the screen resolution making sure the script is displayed 
in the same resolution as captured. For instance, if a script was captured in VGA 
mode and you attempted to display it in SuperVGA mode, the captured xy 
coordinates would be invalid. Therefore, when displaying your script, you should 
use a screen that is the same resolution as the screen used during Capture. 



7.1.1.11 App Wait Delay 

The AppWait ( ) function is inserted into your script file during Capture before a 
windowRcv { ) function to record the amount of time taken to draw a window on 
screen. This function is used during script execution to emulate the application 
delay for drawing a window on screen. During script execution, this function only 
applies to Non-Display mode, because in Display mode, windows would actually be 
activated. 

In the following example, the script recorded an application delay of 1.16 seconds to 
draw the "Program Manager" window. During script execution in Non-Display 
mode, the script will emulate the application delay by pausing the script for the time 
specified. 

The parameter of AppWaitO is the time in seconds of the captured application 
delay. If you wish to change your AppWait delay, you may set a multiplication factor 
with the AppWaitFactor ( ) function. This function multiplies the AppWait delay 
times the factor. For instance, during script execution your application may be 
twice as slow because it is receiving twice as much data from the SUT. You can set 
the AppWaitFactor { ) to .2 so that the script will emulate the extra delay. 



EMPOWER/CS-Vl.O.1 



7-22 

Copynghl PERFORMIX. Inc. © 1995 



User's Guide-Script Development 



Example: 



AppWaitFactor (0.20) ; 
AppWait (1.16) ; 

WindowRcv (" SfDwAcSfSfSfPt " ) ; 



7.1.1.12 WindowRcv 

The WindowRcv () function is inserted into the script during Capture when an 
activated window is drawn on screen and usually follows an AppWait{) call. 
*J Consecutive WindowRcv ( ) functions can be listed within the script file. 

This function is used during script execution in Display mode to ensure that the 
H activated window is drawn on screen. In Non-Display mode, this function is ignored 

% because the AppWait ( ) function emulates the amount of time required to draw the 

jl specified window. 

2 Th e parameters of this function are MS Windows standard two-letter pneumonics 

^ that represent the following commands: 

O Command Description 

Activate Window 
Command 
Create Window 
Destroy Window 
Paint 
Set focus 
System Command 



AC 
Co 
Cw 
Dw 
Pt 
Sf 
Sz 
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Example: 



AppWait {0 .05) ; 

WindowRcv ( "CwPtPtDwCoSf CwCwCwCwCwCwCwCwCwCwSf AcSzPt " ) ; 
WindowRcv ( " PtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPt " ) ; 

CurrentWindow { "Run" , 429, 491, 880, 764} ; 



This function should not be edited in your script file when displaying script 
execution because you change expected activity from when it was captured and, 
therefore, run the risk of breaking the script. 



7.1.1.13 CurrentWindow 

The CurrentWindow ( ) function is inserted into your script file to record all titled 
windows that were activated during the Capture session. This function is used to 
ensure windows are in their captured state during script execution in Display 
mode. It will be listed in Monitor during script execution in Display and Mon-Display 
modes adding context to script execution. 

The parameters of CurrentWindow { ) identify the title of the current window 
(window with focus), define the top left xy coordinates, and then, define the width 
and height of the window's position on screen. If the width and height are both 
zero, the window is minimized. If the x,y coordinates are both zero and width is 
maxwidth and height is maxheight, the window is maximized. If neither of these 
conditions apply, the window is in a normal state. 

During script execution, if the window could not be moved to the specified 
position, the log file will record a warning but script execution will continue. 

The following example demonstrates how CurrentWindow ( ) would appear in a 
script file. The activated window was "Accounting" which appeared on screen in a 
normal state: 
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AppWait{0.39) ; 
WindowRcv{ "ScDwAcSf " ) ; 

CurrentWindowf "Accounting" , 413 , 679 , 1029 , 771) ; 



The following example is a portion of a log file that recorded a warning when a 
Currentwindow( ) function could not execute properly because the window did 
not exist during script execution in Display mode: 

»> ' CurrentWindow( "File Manager ",0,0, MAXWIDTH , MAXHEIGHT ) 
Warning: Unable to find window 

This function should not be edited or removed from your script file because you 
change the state of your Windows desktop from when it was captured and, 
therefore, run the risk of breaking the script. 



7.1.2 Interacting with the SUT 

For you to fully understand the process of interacting with the SUT and the 
EMPOWER/CS functions associated with this process, the general behavior of the 
database environment should first be explained. The following paragraphs and 
sections will introduce you to levels of the database environment that represent 
specific database communication structures, define the actual script statements that 
represent such operations as querying or inserting data, and describe other 
EMPOWER/CS functions that perform various database operations. 



7.1.2.1 Communication Structures 

In the database environment, certain communication structures are defined to 
access the database on the server for retrieving, inserting, or changing data. These 
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communication structures must be accessed in a particular order as explained 
below: 

O "The first level of the database environment is the database environment as a whole. 
An entire environment is defined that identifies the database being accessed. 

O The next level is a log on communication structure. To connect to the database, at 
least one log on communication structure is defined. If the client application 
requires multiple, simultaneous connections, one log on structure is defined for each 
connection. 

O The third level of the database environment is the cursor structure. To process SQL 
requests to the SUT, a cursor communication structure is defined for each SQL 
request. 

In your captured script .c file, you will notice such parameters to various database 
functions as oracle, logi, LOG2, curi, CUR2, etc These parameters are identifiers 
of each level of the database environment that was opened to access the SUT. Each 
level is numbered to link all database operations particular to a certain environment, 
log on, or cursor structure. For example, the call Exec(cuRl) would execute the 
Parse ( ), or SQL, statement that belongs to the cursor, curi. 

The following diagram demonstrates the database environment structure and how 
the SUT is accessed. 
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Accessing the SUT 

Database Environment 



CUR1 

LOG1 ' 

CUR2 



CUR3 

LOG2 ' 

CUR4 




SUT 



7.1.2.2 Procedure for Interacting with the SOT 

Interaction with the SUT occurs when SQL requests are sent to the SUT and then 
processed. SQL requests are represented in the script by the parameter to the 
Parse { ) function which lists a SQL statement 

To access and interact with a database on the server during script execution, 
EMPOWER/CS database functions are called in a particular order. The 
EMPOWER/CS database functions will occur in the script generally based on the 
following standard procedure: 
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Basic Procedure and Script Structure for Database Activity 

□ A database environment is opened, represented by the call Openenv ( ) in 
the script which specifies the database to be accessed 

□ A connection to one or more databases occurs with a Logon ( ) to each 
specified database 

□ One or more cursors are opened, represented by the Open ( ) function in the 
script, to process SQL statements 

□ The SQL statements required to perform database operations such as 
querying, inserting, or deleting data are processed with Parse ( ) 

□ The select-list items of the SQL statement are described as necessary with 
Describe ( ) functions 

□ Bind( ) functions are called for input statements to bind the address of an 
input variable to each placeholder in the SQL statement 

□ For queries, Define ( ) is called to define an output variable for each select- 
list item in the SQL statement 

□ Exec { ) is called to execute the Parse ( ) and, therefore, the SQL statements 

□ For queries, Fetch () and GetNextRowO are called to retrieve and sort 
through specified rows of data 

□ The cursors are closed with close ( ) 

□ A Logoff ( ) function is called for each log on structure to disconnect from 
the specified database(s) 

□ Each database environment is closed with ciosenv( ) 
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The following script segment demonstrates the EMPOWER/CS functions used to 
interact with the SUT: 





Type( H c: \ \accts\\accts~M M } ; 






AppWait<0.22) ; 






WindowRcv ( "CwO^CwOrvC^vOtfCw'' ) 






Openenv ( ORACLE , VERSI0NV6V7 ) 






Username{LOGl, w scott/tiger@FOO H ) ; 




Pas sword ( LOG1 , M t i ger " ) ; 






Logon ( ORACLE , LOG1 ) ; 






WindowRcv ( " Sf AcSf Dw" } ; 






Open (LOG1, CUR1) ; 






WindowRcv ( * AcSf " ) ; 






CurrentWindow ( "Accounts Application" , 189, 82, 685, 449) ; 




Think(4.77) ; 






ButtonPush( "Accounts Application] #c5 355 , 270) ; 


== 


AppWait(5.38) ; 






WindowRcv ( " StCvK^CvK^K^CwC^ ) ; 




Dbset (CURl , DEFER, TRUE ) ; 




n i 


Parse (CUR1, " SELECT ID, FIRST_NAME , LAST_NAME, ADDRESS_LINE_1, ADDRESS_LINE_2 , 




ADDRESS_LINE_3 , PHONE_NUMBER, FAX_NUMBER , COMM_PAID_YTD , ACCOUNT_BALANCE , COMMENTS 




FROM CUSTOMERS " ) ; 






DescribeAlKCURl, 1, 12); 






Dbset (CURl, MAXARRSIZE, 64) 






Define {CURl, M 1 M , STRING, 40); 




Define (CURl, M 2\ CHAR, 21) 






Define {CURl, H 3 N , CHAR, 21) 






Define {CURl, M 4 H , CHAR, 21} 






Define (CURl, n 5\ CHAR, 21) 






Define (CURl, "6* 1 , CHAR, 21) 






Define (CURl, "7", CHAR, 16) 






Define (CURl, "8", CHAR, 16) 






Define (CURl, "9", STRING, 40); 






( continued on following page . ) 
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Define (CURl, "10", STRING, 40); 
Define (CUR1, "11", CHAR, 241); 
Exec {CURD ; 

Dbset(CURl, FETCHSIZE, 64); 
Fetch (CURl) ; 

while {GetNextRow(CURl) ! =NOMOREROWS) ; 



Commit (LOG1) ; 



Close (CURl) ; 
Logoff (LOG1) ; 
Closenv (ORACLE) ; 



Endscenario ( " scriptl " ) ; 



C- The following sections further explain the procedure for interacting with the SUT. 



7.1.2.3 Open an Environment 

As stated in the previous section, the first level of the database environment is the 
database environment as a whole. This level is represented in a script file by such 
database names as oracle, SYBASE2, etc. and is accessed with the function 
Openenv ( ) . The Openenv ( ) function is inserted into the script when a database 
environment is opened. When executing a script, Openenv {) opens an 
environment to specify the database and database version to be used for the 
emulation. 

In some cases, multiple databases may be accessed and activity for each database 
may occur concurrently, therefore, more than one Openenv () call may be listed 
within a script. 
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7.1.2.4 Connect to the SUT 



The second level of the database environment is the log on level which opens a 
connection to the SUT through a log on communication structure. This level is 
defined with a Logon ( ) call in the script and is represented in function parameters 
as a pointer to a log on structure called logi, L0G2, etc. The first log on structure 
defined will be numbered by EMPOWER/CS as logi, the second as LOG2, etc. 

The Logon ( ) function is inserted into the script when a log on connection is 
opened to the database. The parameters to Logon { ) specify to which database the 
script is connecting and the number of the log on structure. 

The script establishes communication with one or more databases by calling a 
Logon { ) function for each connection. Logging on to the database is necessary for 
the subsequent database operations of querying and inserting data. Multiple log on 
structures are possible for each database environment 

To successfully access or log on to the database, a Usemame and Password also are 
defined. Therefore, before a Logon {) function executes, the UsernameO and 
Password () functions are called in the script UsernameO sets the name of the 
user who is logging on to the database and the Password ( ) function sets the user 
password to log on to the database. These functions are inserted into the script file 
when a user name and password are entered to log on to the database. 

The following script segment demonstrates the process of logging on to the 
database, oraclei, from the log on structure logi: 



Type{ "c: \ \accts\ \accts A M" ) ; 
AppWait (0.22) ; 

WindowRcv ( " CwCwCwCwCwCwCw 11 ) ; 
Openenv { ORACLEI , VERSI0NV6V7 ) ; 

Username (LOGI , " scott/ tiger@FOO" ) ; 
Password (LOGI, "tiger") ; 
Logon ( ORACLEI , LOGI ) ; 
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Note: In some cases, you also may notice the functions, AppName ( ) , Hostname ( ) , 
and Servername ( ) before the Logon { ) call in your script. These functions also are 
used to access the database. AppName ( ) specifies the name of the database 
application being used. HostName( ) specifies the name of the host machine where 
the server resides. Servername ( ) is the name of the server on the host machine 
where the database is located. 



7.1.2.5 Open the Cursors 

The third level of the database environment is the cursor communication structure. 
The cursor structure is where the script actually interacts with the database by 
processing SQL requests to the SUT. Cursors are opened with an Open { ) call in 
the script file and are represented in function parameters as a pointer to a cursor 
structure called curi, CUR2, etc. The first cursor opened in a particular log on 
structure will be numbered by EMPOWER/CS as curi, the second as cuR2 t etc. 
The Open ( ) function is inserted into the script when a cursor structure is opened. 

A cursor can be opened only through a successful log on connection and multiple 
cursors can be opened from a single log on. Processing a SQL statement is 
possible only from an open cursor structure. Therefore, such script functions as 

Parse ( ) , Define ( ) , Bind ( ) , Exec ( ) , Fetch { ) , GetNextRow ( ) , etc. which process 
the SQL statement operate only from a cursor structure. The SQL statement is a 
parameter to the Parse () functions and specifies the operations of querying, 
inserting, or deleting data. 

The Open ( ) function will be listed after the Logon ( ) function and before the 
Parse ( ) in your script file. 



7.1.2.6 Parse the SQL Statement 

Parsing the SQL statement associates it with the appropriate cursor in the script. 
Parsing a SQL statement includes sending it to the SUT, verifying its syntax is 
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compatible with the database, and preparing the SUT for subsequent operations 
specified in the SQL statement. The Parse () function is inserted into your script 
when a SQL statement is parsed and sent to the SUT. Every SQL statement in a 
script must be parsed with the Parse ( ) function. Once a Parse ( ) is performed, 
the parsed statement is stored on the database to wait for an Exec { ) call. 

The first parameter of the Parse { ) function identifies the cursor structure that was 
opened with the associated Open ( ) function. The second parameter lists the SQL 
statement to be parsed 

The SQL statement specifies the set of data that is to be operated on by the 
database. This statement is a request to the SUT to select, input, delete, update, or 
retrieve data. Subsequent functions (i.e, Define ( ) , Bind ( ) , Exec ( ) , Fetch ( ) ) 
designate how to perform the database operations and reference the SQL 
statement by listing the associated cursor number in a function parameter. 

Because the SQL statement can be executed only from a cursor structure, Parse { ) 
occurs after an Open ( ) function; and, because the SQL statement is executed by 
the Exec { ) function, Parse ( ) occurs before Exec { ) in the script 

In the following example, the SQL statement for the cursor, curi, begins with " 
select This example demonstrates a Parsed function selecting data for a 
database query: 

Parse (CURI, " SELECT ID, F IRS T — NAME , LAST_NAME, ADDRESS_LINE_1 , 
ADDRESS_LINE_2, ADDRESS_LINE_3 , PHONE_NUMBER , FAX_NUMBER, 
COMM_PAID__YTD, ACCOUNT_BALANCE , COMMENTS FROM CUSTOMERS "); 

The following example demonstrates a sample SQL statement for inserting data: 

Parse (CURI, " INSERT INTO CUSTOMERS { ID, FIRST_NAME, LAST_NAME, 
ADDRESS_LINE_1, ADDRESS_LINE_2 , ADDRESS_LINE__3 , PHONE_NUMBER , 
FAX_NUMBER, COMM_PAID_YTD , ACCOUNT_BALANCE , COMMENTS ) VALUES ( 
789, 'Robert 1 , 'Adams*, ' 1 Maple Lane * , ' Any town* , 'VA, 22222', 
'555-9856', '555-7634', 500, 700, 'Good Job' )"); 
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The following example demonstrates a sample SQL statement for deleting database 
records: 

Parse (CUR1, "DELETE FROM CUSTOMERS WHERE ID = 789 AND FIRST_NAME 
'Robert' AND LAST_NAME = 'Adams* AND ADDRESS_LINE_1 = '1 Maple 
Lane* AND ADDRESS_LINE_2 = ' Anytown* AND ADDRESS_LINE_3 = 'VA, 
22222* AND PHONE_NUMBER = ' 555-9856* AND FAX_NUMBER = '555-7634* 
AND C0MM_PAID_YTD = 500 AND ACCOUNT_BALANCE = 700 AND COMMENTS - 
'Good Job' " ) ; 

Note: If you are using ah older version of an Oracke database, you may notice the 
Sql() function in your script file instead of Parsed. The Sql{) function is 
identical to Parse ( ) except that it does not allow for a deferred parse. See Section 
7.13.1 for more information on deferred parses. 



7.1.2.7 Describe Select-List Items 

If a description of a variable in a SQL query statement was requested by the client 
application during Capture, a Describe { ) function will be inserted into your script 
file. The variable is specified in the function's parameter by a cursor number and 
by the variable's position in the SQL statement. The Describe!) function will 
occur in the script after a Parse ( ) statement and before Define ( ). 

During script execution, Describe () sends a request to the database for a 
description of specified select-list items in the SQL statement. It returns 
information about the select-list items needed to determine how to convert, display, 
or store the data that will be returned when rows are fetched for a query. Such 
returned information can include the name of the variable, the data type, the size of 
the item, whether the data is null-terminated or updateable, etc. 

Note: If you notice the function DescribeAll ( ) in your script, a Describe { ) 
operation was performed describing every seiect-Iist item listed between two 
positions. 
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Example: 

DescribeAll (CUR1, 1, 12); 

In this example, all variables listed in the SQL statement from curi, starting from 
position 1 to position 12, will be described. 

In some cases, you may notice a Descr ibeProc ( ) function instead of 
Describe (). The DescribeProc { ) function describes all variables used in a 
specified stored procedure. A stored procedure is an operation that is stored on 
the database to be executed later. The procedure must be described before a parse 
is completed. Therefore, this function will occur in the script before Open ( ) and 
m Parse ( ) . 

■=5j=< 

Cj 7.1.2.8 Bind the Addresses of Input Variables 

w Some SQL statements require that data be input to the database. Placeholders for 

^ input variables in the SQL statement mark where specific data must be input and 

are indicated by leading colons (Example: :NAME). If a SQL statement requires data 
Q to be input to the database, a Bind ( ) function will be inserted into the script to bind 

each placeholder to a variable that is to be passed to the database. Therefore, when 
JtJ the SQL statement is executed, the database will receive the data that was placed in 

p the input variables. 

The parameters of the Bind ( ) function identify the variable by the cursor number 
of the associated SQL statement, the variable placeholder listed in the SQL 
statement, the variable's data type, and the variable's length in bytes. 

The Bind( ) function is listed in the script after a Parse ( ) statement and before 
Exec ( ) . 
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The following example demonstrates a Bind{) function inserted into a script for 
the variable, x: 



Parse (CUR1, " SELECT EMPNO, ENAME , JOB, MGR, HIREDATE, SAL, COMM, 
DEPTNO FROM EMP WHERE EMPN0=:X" ); 



Bind(CURl, "X n , STRING , 10); 



Note: If you notice a BindpO function in your script a Bind{) operation was 
performed for a variable based on its position in the SQL statement instead of 
placeholder name. The parameter would specify a position instead of a name. 
Bindp ( ) binds the variable's position to the variable. 

If a variable was inserted and then retrieved, the BindDef ine { ) function is 
inserted into the script. BindDef ine ( ) inputs a variable to the database and then 
gets a new value. Usually, the value returned is the old value. For example, if the 
SQL statement specified that the value smith be inserted into a record to 
overwrite the existing value Jones, BindDefineO would specify Smith as the 
new value for the record and then return the old value Jones to the variable. 



7.1.2.9 Define 

The Define {) function is inserted into the script when output variables are 
defined for storing data to be fetched from the database. The SUT places data in 
these output variables when a Fetch ( } function is called. Define () functions are 
used only when fetching records from the database for a query. 

Define { ) associates the address of an output variable in the program with each 
select-list item in a SQL query statement. The Define () function defines each 
select-list item in the SQL statement by a cursor number, the item's position in the 
SQL statement, the variable's data type, and the variable s length. The positions in 
the SQL statement are defined beginning with 1 for the first (or left-most) select-list 
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item, 2 for the second, and so on. The Define ( ) function is listed in the script 
after a Parse ( ) statement and before Fetch ( ) . 

The following script segment demonstrates the Defined statements defining 
variables for each select-list item of the SQL statement. Notice in the first 
Define () statement below, the variable position "1" refers to id in the SQL 
statement 



Parse (CURl, " SELECT ID, FIRSTJNAME, LAST_NAME, ADDRESS_LINE_1 , 
ADDRESS_LINE_2, ADDRESS_LINE_3 , PH0NE_NUMBER, FAX_NUMBER, 
COMM_PAID_YTD, ACCOUNT„BALANCE , COMMENTS FROM CUSTOMERS "); 

DescribeAll (CURl, 1, 12); 



Dbset(CURl,MAXARRSIZE, 64) ; 



Define (CURl, "1" , 

Define (CURl, "2" , 

Define (CURl, "3" , 

Define (CURl, "4", 

Define (CURl, " 5 " , 

Define (CURl, "6" , 

Define (CURl, "7", 

Define (CURl, " 8 " , 

Define (CURl, "9" , 

Define (CURl, "10" 

Define (CURl, "11" 
Exec (CURl) ; 



STRING, 40); 
CHAR, 21) 
CHAR, 21) 
CHAR, 21) 
CHAR, 21) 
CHAR, 21) 
CHAR, 16) 
CHAR, 16) 
STRING, 40); 

STRING, 40) ; 

CHAR, 241); 



7.L2.10 Execute the Parse 

The Exec ( ) function executes the operations specified in the associated SQL 
statement. This function is inserted into your script when a SQL statement is 
executed on the SUT, 
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Exec ( ) executes the SQL statement by specifying the data the script will be 
fetching or by inputting the values in all bind variables to the database. 

The parameter of Exec { ) identifies the cursor of the associated SQL statement. 

7.1.2.11 Fetch the Rows of Data for a Query 

After the specified output variables are defined and the SQL statement has been 
executed, the rows of data that satisfy a query are fetched. In your script, the 
Fetch () function is inserted when the data specified in the SQL statement to 
satisfy a query is retrieved. During script execution, when the number of rows of 
data specified in the option fetchsize is fetched from the database, the data is 
placed into the defined output variables in a buffer on your UNIX script driver 
machine. The parameter of Fetch {) specifies the cursor structure for the 
associated SQL statement 

The number of rows of data that are fetched is specified in the Dbset ( ) function 
in the following format 

Dbset (curnum, FETCHSIZE, n) 

The parameter fetchsize sets the number, n, of rows of data to fetch. See Section 
7.1.3.1 for more information on setting the fetchsize. 

Each Fetch ( ) statement returns the next row from the set of rows that satisfies a 
query. After the last row has been returned, the next fetch will return an error that 
no remaining rows could be fetched 

The Fetch { ) statement is called only after the Parse { ) and Exec ( ) functions have 
been called. 
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In the following script segment, Fetch ( ) is called for the cursor, CUR1: 



Parse (CURl, " SELECT EMPNO , ENAME , JOB, MGR, HIREDATE , SAL, COMM, 
DEPTNO FROM EMP , FOR UPDATE OF EMPNO , ENAME, JOB, MGR, HIREDATE , 
SAL, COMM, .DEPTNO"); 



Exec (CURl) ; 
Fetch (CURl) ; 



Note: If you notice a FetchRaw( ) function in your script, this function signifies 
that binary data was specified in the SQL statement to be retrieved. FetchRawf ) is 
used because the data is too large to transfer across the network at one time, 
instead, the data is transferred in portions at a time. The parameters to FetchRaw( ) 
identify the cursor number of the associated SQL statement, the position of the 
associated select-list item in the SQL statement, the data type of the output variable, 
and the length in bytes of the data to be retrieved 

In your script file you also will notice the function GetNextRow( ) which is inserted 
after Fetch ( ) . The GetNextRow ( ) function is inserted into the script when the 
client application sorts through the fetched rows of data. 

During script execution, GetNextRow( ) is used to view the contents of the fetched 
rows of data one at a time after they are fetched onto the UNIX script driver. This 
function generally occurs in a loop and may be used to verify that the requested 
data was retrieved or to locate a specific row of data. 

The following example demonstrates calling GetNextRow ( ) in a script file: 



Fetch (CURl) ; 

while (GetNextRow (CURl) ! =NOMOREROWS ) ; 
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7.1.2.12 Close the Cursor Structures 

Before a client application that processed SQL statements exits, each open cursor 
is closed. Once a cursor is closed, no additional operations can be performed on 
that cursor. 

The EMPOWER/CS function, closed, is inserted into the script for each cursor 
structure that was closed. When an executing script exits, each cursor opened in a 
particular log on structure is closed with a close ( ) function (one for each Open ( ) 
call). 



7.1.2.13 Disconnect from the SUT 

When a client application that processed cursors exits, each connection to the 
database is closed. The Logoff () function is inserted into the script for each 
connection to the database that was closed. All active cursors on the specified log 
on structure must be closed before the log on structure is closed. 



7.1.2.14 Close the Environment 

The function ClosenvO is inserted into a script file when a database environment 
is closed. 

A ClosenvO function closes each environment that was opened with each 
Openenv ( ) . After a database environment is closed, no further log on connections 
can be made within the specified database environment. Each database 
environment in a script must be closed before an executing script exits. 
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The following example demonstrates that the database environment oracle was 
closed: 



Close (CURl) ; 
Logoff (LOG1) ; 
Closenv (ORACLE) ; 

Endscenario ( " scr iptl " ) ; 



7.L3 Other Database Functions 

The following sections describe other EMPOWER/CS database functions that may 
appear in your script file. 



7.13.1 Dbset 

Client applications may specify certain options that control the behavior of the 
database environment The Dbset ( ) function is inserted into the script when such 
options are set according to the client application and the SUT and how they 
interact. This function may occur throughout a script and it specifies various 
options for the database environment 

The syntax for Dbset { ) follows: 
Dbset {num, opt, value) 

The parameter num will be an environment number, a log on structure, or a cursor 
number; the parameter opt specifies the database option being set; and, value 
represents either a numerical or string value, or true or false, depending on the 
option being set. 



EMPOWER/CS-Vl.0.1 



7-41 

. CopynsW PERFORMIX. Inc. © 1995 



User's Guide— Script Development 



The DbsetO options that commonly will show up in your scripts are defined 
below: 

Option Description 

fetchsize Specifies the number of records to fetch from the database 

when a Fetch { ) function is executed. The Dbset ( ) function that 
sets the fetchsize will occur before a Fetch ( ). The fetchsize 
value can not be larger than the value specified for maxarrsize. 
If the fetchsize was specified as 50 and maxarrsize was 
specified as 20, EMPOWER/CS will reduce the fetchsize to 
20. The default value for this option is 1 which means that if 
fetchsize is specified as zero or lower, EMPOWER/CS 
automatically sets the value to 1. 

» 

maxarrsize Sets the maximum array size for retrieving or inserting records. 

If the array size is set at 20, 20 rows of data can be inserted or 
fetched If this option is set at 20, then 20 placeholders are 
allocated for inserting or fetching 20 rows of data. The Dbset { ) 
function that sets the maxarrsize will occur before the Bind( ) 
and Define ( } functions in a script The default value for this 
option is 1 which means that if maxarrsize is specified as zero 
or lower, EMPOWER/CS automatically sets the value to 1. 

insertsize Specifies the number of rows of data to be inserted into 
the database. This option will be listed before the Data ( ) 
function in a script in the format Dbset (curi , insertsize, 
n). This option allows array binding. For example, if n is 0 or 1, 
one row can be inserted at a time into the database. If n is 50, 50 
rows will be inserted into the database and 50 Data ( ) lines must 
be listed for every row before Exec ( ). The insertsize value 
can not be larger than the specified maxarrsize. The default 
value for this option is 1 which means that if insertsize is 
specified as zero or lower, EMPOWER/CS automatically sets the 
value to 1. 

offset Specifies the offset for inserting records in an array. This option 

is used with the insertsize option. If an array includes four 
names and the offset is set to 2, the second name will be the 
starting point for inserting data. The Dbset { ) function specifying 
this option will occur before an Exec ( ) function. If the offset is 
specified as a range larger than the maxarrsize, a database error 
will occur- 
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waitres Specifies whether or not to wait for resources. If this option is 

set to true, the script will wait indefinitely for requested 
information from the database, [f it is set to false and the script 
does not receive the requested information, the script will 
receive an error that the resource was not available. Script 
execution will then either continue or exit based on the condition 
set in Dberror { ) . The default value of this option is true. 

defer Specifies whether or not to defer the Parse ( ) statement. 

If this option is set to true, a deferred parse will be performed 
when the script encounters the Parse ( ) function. If the option is 
set to false, a normal Parse ( ) is executed. The default value of 
this option is false. 

Normally, the SQL statement is sent over to the database when 
the script encounters Parse ( ) and processed to ensure it is 
semantically correct The SQL statement is stored to wait for the 
Exec ( ) call that' actually executes it If defer is set to true, the 
SQL statement is not sent over to the database until the script 
encounters an operation that requires input from the database 
Such as Exec { ) or Describe ( ) . 



A complete list of Dbset { ) options that may appear in the script file is listed below 
with brief descriptions. This list is divided into those options that set integer values 
and those options that specify true or false. The list also designates the options 
that apply specifically to the database environment as a whole, to the log on 
structure, or to the cursor. 



Integer Value 



Option 



Description 



FETCHSIZE 

MAXARRSIZE 

INSERTSIZE 

OFFSET 

MAXCONNECT 

PACKETSIZE 

ROWCOUNT 

TEXTS I ZE 

ISOLATIONLEVEL 

AUTH0FF 



number of rows to be fetched 

maximum number of rows to be fetched or inserted 

number of rows to.be inserted 

row number where to begin inserting 

maximum number of connections in an environment 

maximum packetsize on logon connection 

maximum number of rows to return 

limit on size of text or image data 

transaction isolation level 

turns specified authorization off 
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authon turns specified authorization on 

curread security label specifies cursor read level 

curwrite security label specifies cursor write lev 

datefirst which day of week is first 

dateformat format of date 

identityoff disable inserts into table identity column 

I dent it yon enable inserts into table identity column 



TRUE or FALSE 



Option 

DEFER 

UPDATE 

READONLY 

SAVEOPTS 

FORCELOGOFF 

FORCEEXIT 

RECOMPILE 

RET P ARAM 



Description 

deferred parse 

cursor is for updating 

cursor is read only 

do not deallocate the structure 

force logoff 

force exit 

recompile stored procedure before executing 
return parameter 



Database environment only 

truncate truncate data 

interrupt application can be interrrupted 

Database environment or logon structure 



ANSI_BINDS 

DEFER_IO 

ASYNC_IO 

SYNC_IO 

EXTRA_INF 

EXPOSE FMTS 



force ansi style binds 
deferred io 
async io 
sync io 

return extra information for error 
expose formats 



Logon structure 

BULKCOPY 

ASYNCNOTIFICATION 

DIAG_TIMEOUT 

APPSECURITY 

SYBSECURITY 

ENCSECURITY 

TRUSTSECURITY 

ANSI NULL 

ANSI PERM 



allow bulk copy on connection 
asynchronous notification 
what to do on a timeout 
application defined security 
sybase defined security 
encrtyped security 
trusted security 
ansi style nulls 
ansi style permissions 
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ARITHABORT 

ARITHIGNORE 

CURCLOSETRAN 

WON STAND SQL 

FORCEPLAN 

FORMATONLY 

GETDATA 

NOROWCOUNT 

PARSEONLY 

QUOTEDIDENT 

PARSETREES 

SHOWPLAN 

IOSTATS 

TIMESTATS 

I GNORETRUNC 



what to do on arithmetic errors 

what to do on arithmetic div. by 0 

close all cursors on end transactions 

flag non standard sql 

force plan or not 

only send format for data 

returns extra information on every sql statement 

row count 

only check syntax, do not execute 

all double quotes signify identifiers 

returns parse resolution trees 

generates a description of procedure plan 

return internal io statistics 

return time statistics 

ignore truncation errors 



Cursor 

AUTOCOMMIT 
WAITRES 
SPECIAL 
HIDDEN KEYS 



commit on every exec 
wait for resources instead of error 
Sybase version of cursor 
expose hidden keys 



7.1.3.2 Data 

The Data{) function is used with database operations for inserting or updating 
data. It specifies the data to be input to the database by listing the data for each 
input variable specified with Bind(), Therefore, it will follow all BindO functions 
and will occur before Exec ( ) . This function is inserted into the script when data is 
specified to be input to the database. 

The str parameter is pipe-delimited and lists the data for each input variable that 
was defined with Bind{ ). The data listed in this str parameter will be listed in the 
same order as it was specified in the Bind ( ) functions. 

The DbsetO option insertsize applies to this function in that the number of 
Data ( } functions inserted will correspond to the value of insertsize. 
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Example: 



Parse (CUR1, 


SELECT 


ENAME, EMPJOB, WHERE ENAME =: name . . 


. ) ; 


Bind (CURl, 


"NAME" , 


STRING, 5); 




Data (CURl, 


" SMITH " ) 







In this example, smith is the data to be entered into the database for the cursor, 

CURl. 

In another example, a SQL statement may include the following: 

. . . EMPNO , ENAME , EMP JOB WHERE EMPNO= : empno , ENAME = : name , 
EMPJOB=:empjob. . . 

A Data { ) line that refers to this SQL statement may look like the following: 

Data{CURl, "123 | Smith | typist" ) 

123 would correspond to empno, Smith would correspond to ename, and typist 
would correspond to empjob. 

Because all users would not make the same entries to the database, you may edit 
this function to vary the data that is inserted into the database during multi-user 
emulations for a more realistic load You can edit the Data ( ) functions in a set of 
scripts so that each emulated user inserts a different record. For example, if a 
Parse () statement contains where name = smith, and the Data { ) line is 
Data {CURl, "smith"), you could change this Data{) line to Data(cURl, 
" jones " ) or Data { CURl , " adams " ) for each emulated user. 
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7.133 SqlExec 

[f you notice a SglExec ( ) function in your script, a SQL statement was executed 
that contained no input or output variables. The SqlExec ( ) function includes four 
database operations. It opens a cursor, parses a SQL statement, executes the 
Parse { ) , and closes the cursor. When this function is used, no operations such as 
Describe ( ) , Bind ( ) , Define { ) , Fetch ( ) , etc. are necessary. For example, it may 
be used when a database operation only requires joining two tables. 

The syntax for this function is: 

SqlExec (lognum, sqlstmt) 

The lognum parameter designates the log on communication structure and 
sqlstmt lists the SQL statement 



7.13.4 Commit, Rollback 

The Commit () function is inserted into the script when database processing is 
committed to the database. This function commits to the database all processing the 
script has completed (i.e., updating records, deleting records, adding records, etc.) 
since processing was last committed to the database. Its parameter may specify a 
log on or cursor structure for which operations are committed. 

The Rollback () function may be inserted into the script if database operations 
are not committed but are rolled back since data was last committed. Rollback ( ) 
restores the database to its original state since the last commit was executed. 

These functions may appear throughout the script dependent on the behavior of 
the client application and the SUT. 
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7.1.4 Editing Database Functions 

The EMPOWER/CS database functions translate client application and database 
interaction and are inserted into the script as the associated actions occur. This 
process ensures that during script execution a load is generated on the SUT as 
close to the real interactions as possible. Because the EMPOWER/CS database 
functions are not user-defined but are inserted into your script based on how the 
client application interacts with the SUT, you generally should not attempt to edit 
these functions or remove them from the script 

Most of the database functions should not be edited because they are inserted 
during Capture in a way specific to the application running from the PC to the SUT. 
If you change these functions from when they were captured in the script file, you 
may drastically alter the expected behavior of the application and SUT and 
therefore, break your script during execution. 

However, simple edits can be made to some of the DbsetO options and more 
complex edits can be made for the Data() and Parse {) functions to enhance 
multi-user emulations. 

Because all users would not make the same entries to the database, you may edit 
the Data!) and Parse () functions to vary the data that is inserted into the 
database during multi-user emulations for a more realistic load. You can edit the 
Data { ) functions in a set of scripts so that each emulated user inserts a different 
record. 

The Dbset { ) option, fetchsize, can be changed to see how a larger or smaller 
fetchsize value affects the performance of your SUT during script execution. 
Please note that the fetchsize value can not be larger than the maxarrsize value. 



EMPOWER/CS-Vl.0.1 



7-48 

Copyright PERFORMIX. Inc. © 1 995 



User's Guide— Script Development 



7.1.5 Comments 

As with all C language programs, your script file should include comments to 
indicate the structure of the script Comments also are useful for interpreting the 
log file. 

Comments are entered either during Capture or when editing your script file. They 
are enclosed by the /* and */ characters and may span multiple lines in a script, but 
may not be nested. 



7.2 Data Types 

The following is a list of the EMPOWER/CS data types that may be listed in the 
database script functions, Bind{ ) and Defined . Format lists how the data types 
are represented in the script as C language data types. This format does not 
necessarily represent how the data type is converted and stored on the database. 



Type Format 

number Internal database binary 

decimal Internal database binary 



Money and Date Data Types 
Type Format 
MONEY dolIars.cents 
LONGMONEY dollarsxents 

DATE day/month/ year hour:minute:seconds 

LONGDATE day/ month/ year hour:minute:seconds.milliseconds 



Example 
103.45 
103 .4500 

02/10/95 10:06:35 
02/10/95 10:06:35.23 



The format for the date data type must be 17 characters in length. The format for 
the longdate data type must be 20 characters in length. 
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Numeric Data Types 



Type 


Format 


BYTE 


char 


SHORT 


short 


INT 


int 


UINT 


unsigned int 


DOUBLE 


double 


FLOAT 


float 


BOOL 


char 



For the remaining data types, the format specifies the maximum length for the 
character array. 

Non null- terminated characters 
Type Format 

LONGCHAR char [ 2 A 3 1 - 5 ] 

CHAR char [2000] 

MEDCHAR cha r [ 6 5 5 3 5 ] 

SHORTCHAR char [255} 

Mull- terminated strings 
Type 

LONGSTRING 
STRING 
SHORTSTRING 

Binary data 
Type 

LONGBINARY 
SHORTB I NARY 
BINARY 
IMAGE 

Encrypted data 
Type 

SECURITYl 
SECURITY2 



Format 

char[2 A 31-l] 
char[2001-l] 
char[256-l] 



Format 

char [2 A 31-1] 
char[256] 
char [65535] 
char[2~31-5] 



Format 

char [ ] 
char [2000] 
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73 Script Arguments 

Arguments can be passed to the script when the script is executed at the 
EMPOWER/CS command line or when a set of scripts is executed with the Multi- 
User testing tool, Mix. Arguments deliver information to a script to control how the 
script executes. 

Arguments may be used to send a random number seed to a script to control a 
random sequence of commands. You can pass the same seed value to a script to 
obtain the same sequence of commands. 

Arguments also may be used to control the execution of functions in the script. You 
may have designed the script to contain functions that test different parts of your 
application. The argument can specify which functions execute at what time and in 
what sequence. 



7.3.1 Argument Syntax 

The script receives arguments as parameters when the script executes. Arguments 
passed to the script (which do not include options) are stored as variables in the 
argv[] array. The number of elements in the argv[] array is defined by the 
variable argc. 

EMPOWER/CS will define these argument variables automatically as follows: 

int argc ; 
char *argv[] 

These variables can be used subsequently in the script. The number of arguments 
(and therefore the number of elements in the array) is limited only by your UNIX 
script driver which generally imposes no practical limitation on script execution. 
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When a script is executed, the following variables are defined: 

argv[0] = the executable script name 
argv[l] = the log file name 

Arguments specified after the log file name in the script command are stored as 
argv [2], argv [ 3 ] , and so on. You must specify a log file name if you want to 
specify other arguments. If you specify other arguments without specifying the log 
file, EMPOWER/CS will use the first argument as the log file name, thus creating an 
error. 



7.3,2 Argument Examples 

The following example illustrates a script execution: 

$ scriptl -d vagrant logl 1 3 wendy passwordl 

script 1 is the name of the binary script created by the Cscc tool. The option -d 
and vagrant specify that the activities will be displayed on the PC named vagrant, 
logl is the name of the log file that will be created when the script is executed. 
The parameters 1, 3, wendy, and passwordl are arguments that will be accessed 
during script execution. 1 and 3 will be used as arguments for EMPOWER/CS 
functions; wendy will be used as the log in ID; and workdir will be the emulated 
user's password. 



These arguments are accessed by the script through the variables argc and argv. 
The values of the variables are: 



argc - 6 

argv [ 0 ] = 

argv [ 1 ] = 

argv [2] = 

argv [3] = 

argv [4] = 

argv [5] = 



scriptl 

logl.l 

1 

3 

wendy 
passwordl 
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The source script file (the .c file) is edited to use these variables as in the following 
example: 

Thinkunif orm (atoi (argv [2 ] ) , atoi (argv [3 ] ) ) ; 
Seed (atoi (argv(3] ) ) ; 

This example shows how the think time is varied in the script. The values of the 
variables argv [2] and argv [3] represent the limits of the think time distribution. 
The value of argv [3] also is used as the seed of the random number generator 
used to generate the sequence of think times. 

The variable array argv[] contains character string variables. Since the 
EMPOWER/CS functions Thinkunif orm ( ) and Seed() take integer arguments 
rather than character strings, you must use the C library function atoi ( ) to convert 
the character strings to integers. 

The resulting log file entries for the think time functions will be: 

ThinkuniformU .000, 3 . 000) 
Seed(3.000) 



7 .4 Script Variables 

EMPOWER/CS scripts are C language programs and therefore, you may use 
standard C variables in the script source file. All variables used in a script must be 
defined at the beginning of the script with the exception of argc and argv, which 
are defined automatically as described in the previous section. 



EMPOWER/CS-Vl.0.1 



7-53 

Copyright PERFORMIX. Inc. © 1995 



User's Guide— Script Development 



Variables are defined with the int. char, float, and double C language 
statements. These statements define variables as follows: 



int - integer 

char - character 

float - single precision floating point 

double - double precision floating point 



These statements may be used to define several variables with the variables 
separated by commas. They also are used to define an array. The following 
examples show definitions of each variable type: 



int i, j, k; 
int i_array[10] ; 
char c; 

char product [20]; 
char *product_ptr ; 
float weight; 
double iq; 



In these examples, the variable array i_array contains ten integers, accessed as 
i_array [0) through i_array [9], The product array can contain 20 characters. 
The variable *product_ptr is used to point to a character string. 

After variables are defined, they may be assigned values: 

i = 10; 

i_array(3] = 17 

c = ' a ' ; 

iq = 17.325; 

productjJtr = "072148"; 



You also may define a variable and give it a value in one statement: 
int i = 11 

To use a variable in a script, simply reference it by name. 



EMPOWER/CS-Vl.O.1 



7-54 

Copyright PEHFORMIX, Inc. © 1995 



User's Guide— Script Development 



7.5 Editing Your Scripts 

After you have created a script with Capture, you likely will want to edit the script to 
change or add script functions. Of course, the changes you make to your scripts are 
driven by your testing goals but EMPOWER/CS scripts generally are edited to 
achieve the exact emulation environment desired. Because EMPOWER/CS scripts 
are actually C language programs, they can be edited to include branching and 
looping. Special EMPOWER/CS functions can be added to your scripts for 
advanced control of script execution. The following sections describe 
EMPOWER/CS functions that can be inserted into your scripts only by editing, and 
also describe methods for branching and looping. 



7.5.1 Recording Messages 

The Log ( ) function records a message in the executed script's log file. Log ( ) 
functions are similar to comments in that they provide help in following the 
structure of a script. The parameter of the Log ( ) function must be a character 
string. 

The Noted function is used to place a note in the "Mote" column of the 
EMPOWER/CS Monitor View 5 during script execution. The parameter of Note ( ) 
is a character string which is saved in the log file and subsequently displayed by 
Monitor. 

The inote() function specifies a message that also will appear in the "Mote" 
column of Monitor View 5. The parameter of inote ( ) is an integer that will be 
displayed by Monitor. 

You can insert these functions into your script as needed when you edit your script 
file. 
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7.5,2 File Input/ Output Functions 

Creating scripts that read input files on the UNIX script driver is a common practice 
during load testing. Such input files may contain names, addresses, phone numbers, 
etc., that are used for emulating database queries and updates. EMPOWER/CS 
allows you to have a separate input file for each emulated user, or multiple users 
can share a single input file. Using a single input file is often more convenient since 
you do not have to maintain many files for large tests. 

EMPOWER/CS provides a convenient way for scripts to read from an input file, 
ensuring that data for each script is unique. The File I/O functions are used in 
scripts to read and write files which is useful for load tests requiring interaction 
with data files on the UNIX script driver machine. These capabilities also are useful 
in simplifying complex scripts such as database entry scripts. The EMPOWER/CS 
file input/output functions allow you to read data from a file, send data from the file 
to the SUT, receive data from the SUT, and write those data to a file. These 
functions simplify the C language statements that would need to be added to 
accomplish the same thing. You can insert File Input/Output functions when editing 
your script 

The environment variable e_fiopath can be used to specify the directory in 
which the files to be accessed reside. A file must be opened before it can be 
accessed with the file input/output functions. Fioopen may be used to open a file. 
Also, the Fioreadline, Fioreadf ield, Fioreadchar, and Fiowritechar 
functions automatically open the file before reading from or writing to it The 
function Fioshare is used to identify a file that is to be shared. If a file contains 
NULL characters, an error will occur when the file is read by an input/output 
function. 

Three global variables are used for file input/output They are defined 
automatically as follows: 

unsigned char *FIOBUFFER 

int FIOLEN 

int FIOBUFFERSZ 
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The variable fiobuffer is a pointer to the characters read from the file. This 
variable often is used when sending data read from a file to the SUT. The variable 
fiolen is the number of valid characters in fiobuffer. If the value of fiolen is 
less than or equal to zero, then either an error occurred or the end-of-file was 
reached. The variable fiobuffersz is the maximum size of the data that can be 
read at one time. The default value of fiobuffersz is 512 characters. If the value 
of fiobuffersz is redefined in a script, it must be redefined before any file 
input/ output functions that reference the file are encountered. 



The file input/ output functions are: 



Fioshare 

Fiounshare 

Fioopen 

Fioclose 

Fiodelimiter 



Fioreadline 
Fioreadf ield 
Fioreadf ields 
Fioreadchar 
Fiowritechar 



Fioskipline 
Fioskipf ield 
Fioskipchar 



Fioseek 

Fioautorewind 

Fiorewind 



These functions are described in the following sections. 



7,5.Z1 Fioshare 

The syntax for this function is: 

Fioshare { filename) 

The Fioshare {) function identifies a file that is to be shared. It must be called 
before any other File I/O functions are called to reference the same file. Fioshare 
in a script presumes execution of the fioshare command at the UNIX script 
driver's shell prompt The fioshare command creates a global variable that 
contains the offset for the next byte to be read from a shared file. The value of the 
variable (offset) remains between tests, so you can continue to read an input file 
from the point left by the previous test This saving of the offset is useful in tests 
that corrupt a database on the server. The ability to avoid the same transactions 
means you can avoid restoring the database before every test You must execute 
the fioshare command if you want to resume reading from the beginning of the 
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input file. For this reason, f ioshare is often run from Mix command files that set 
up for a new test 

For example, assume we require scripts to read commands from an input file called 
cmds . The following command will create the global offset for the file: 

$ £ ioshare cmds 

A segment in the script to read from cmds might look like the following. Each 
instance of this script will read different lines. 



F ioshare ( " cmds * ) ; 

Fioreadline { " cmds " ) ; 
if (FIOLEN == -1} 
{ 

Log ("end of the date file"); 
exit (1) ; 

} 

Type ( FIOBUFFER , " *M" , " " ) ; 



The global offset is stored in an EMPOWER/CS global variable. (Refer to the Multi- 
User Testing Manual for more information on global variables.) This global variables 
name is the inode of the shared file. This can be confirmed by typing the UNIX 
"is -i" command with an argument of the shared file and then running the 
gv_stat command, which lists the names, status, and value of EMPOWER/CS 
global variables. For example: 



$ fioshare cmds 




$ Is -i cmds 




59449 cmds 




$ gv_stat 




gv_stat: EMPOWER/GV VI . 0 . 0 , 


Serial#R000OO-0O0, Copyright PERFORMIX, 


Inc. 1988-95 




Name Type 


Value Allocated Protector 


59449 long int 


0 0 
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7,5.2.2 Fiounshare 

The Syntax for this function is: 
Fiounshare { filename) 

The Fiounshare ( ) function discontinues the sharing of a file. The shell command 
fiounshare can also be executed to discontinue the sharing of a file. Neither the 
function nor the command remove the global variable offset for the file. They 
simply mark the global variable as being unusable for further input/output 
functions. 

The Fiounshare function disables the sharing of the file offset only for the script 
that executes the function and the fiounshare shell command disables the sharing 
of the file offset for all scripts currently sharing the file. 

To remove the global variable offset, you must use the gv_rm shell command to 
remove the variable named in the gv_stat output listed above. For example: 

$ gv_rm -f 59449 



7.5.23 Fioopen 

The syntax for this function is: 

Fioopen { filename, mode) 

The Fioopen ( ) function opens the file filename. The parameter mode specifies 
how the file is opened. If mode is V\ the file is opened at the beginning for 
reading only. If mode is V, the file is truncated or created for writing only. If mode 
is "a", the file is opened at the end for writing only. If mode is "r+'\ the file is 
opened at the beginning for reading and writing. If mode is "w+ M , the file is 
truncated or created for reading or writing. If mode is 'W, the file is opened at the 
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end for reading and writing. If the function is successful, zero is returned. If an 
error occurs, -1 is returned. 

7.5.2.4 Fioclose 

The syntax for this function is: 

Fioclose ( filename) 

The Fioclose () function closes the file filename. If the function is successful, 
zero is returned. If an error occurs, -1 is returned. 

7.5.2.5 Fiodelimiter 

The syntax for this function is: 

Fiodelimiter ( filename, delimiters) 

The Fiodelimiter ( ) function defines the field delimiters for the file filename. 
The default is "\t\n" and "\n" is always a delimiter ("Nt" is tab and "\n" is new line 
or linefeed). If the function is successful, zero is returned If an error occurs, -1 is 
returned. 

7.5.2.6 Fioreadline 

The syntax for this function is: 

Fioreadline ( filename) 
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The Fioreadline ( ) function reads the next line from the file fil ename into 
fiobuffer. If the file is not currently open (see Fioopen), it is opened 
automatically. A pointer to fiobuffer is returned. If fiolen is less than or equal to 
zero, then either an error occurred or the end-of-file was reached. 



7.5.2.7 Fioreadfield 

The syntax for this function is: 
Fioreadfield ( filename ) 

The Fioreadf ield( ) function reads the next field from the file filename into 
fiobuffer. The fields are separated by the delimiter (see Fiodelimiter). If the file 
is not currently open (see Fioopen), it is opened automatically. A pointer to 
fiobuffer is returned. If fiolen is less than or equal to zero, then either an error 
occurred or the end-of-file was reached 



7.5.2.8 Fioreadfields 

The syntax for this function is: 

Fioeadfields { filename, n, argO, arg[n] ) 

This function reads n fields from the file filename as delimited by field delimiters. 
(The default is " \t\n" , where n \n" is always a delimiter.) Fields are copied into 
arguments. If the specified file is not currently open, this function automatically 
opens it for reading. 

The Fioreadfields ( ) function returns a pointer to fiobuffer. 
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7.5.2.9 Fioreadchar 

The syntax for this function is: 

Fioreadchar ( filename , n) 

The Fioreadchar ( ) function reads n bytes from the file filename. If the file is 
not currently open (see Fioopen), it is opened by Fioreadchar () . A pointer to 
fiobuffer is returned. If fiolen is less than or equal to zero, then either an error 
occurred or the end-of-file was reached. 



7.5.2.10 Fiowritechar 

The syntax for this function is: 

Fiowritechar { filename, buf, n) 

This function writes n bytes from the buffer, buf, to the file filename. If the file is 
not currently open (see Fioopen) t it is created or truncated and opened for reading 
and writing automatically. If the function is successful, zero is returned. If an error 
occurs, -1 is returned. 



7.5.2.11 Fioskipline 

The syntax for this function is: 

Fioskipline { filename, n) 

The Fioskipline { ) function skips forward n lines in the file filename. If the file 
is not currently open (see Fioopen), it is opened automatically. The variables 
fiobuffer and fiolen are updated with the last line read. If the function is 
successful, zero is returned. If an error occurs, -1 is returned. 
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7.5,2.12 Fioskipfield 

The syntax for this function is: 

Fioskipfield ( filename, n) 

The Fioskipf ield( ) function skips forward n fields in the file filename. The 
fields are separated by the delimiter (see Fiodelimiter). If the file is not currently 
open (see Fioopen), it is opened automatically. The variables fiobuffer and 
fiolen are updated with the last field read. If the function is successful, zero is 
returned. If an error occurs, -1 is returned. 

73.2.13 Fioskipchar 

gg The syntax for this function is: 

4^ Fioskipchar ( filename, n) 

P The Fioskipchar ( ) function skips forward n characters in the file filename. If the 

flj file is not currently open (see Fioopen), it is opened automatically. The variables 

fiobuffer and fiolen are updated with the last characters read (the number of 
;3l characters used to update fiobuffer and fiolen is defined by the variable 

~ fiobuffersz). If the function is successful, zero is returned. If an error occurs, -1 is 

returned. 

7.5.2.14 Fioseek 

The syntax for this function is: 

Fioseek ( filename , offset) 

The Fioseek ( ) function sets the file pointer to a specific byte in the file. The next 
byte read or written will occur at of f set bytes from the beginning of the file. If the 
value of offset is equal to fioend, the seek will occur to the end of the file. If the 
function is successful, zero is returned. If an error occurs, -1 is returned. 
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7.5.2.15 Fiorewind 

The syntax for this function is: 

Fiorewind ( filename) 

The Fiorewind { ) function rewinds the file pointer to the beginning of the file for 
the file filename. If the function is successful zero is returned. If an error occurs, 
-1 is returned. 



7.5.2.16 Fioautorewind 

The syntax for this function is: 

Fioautorewind { filename) 

The Fioautorewind ( ) function automatically rewinds the file pointer to the 
beginning of the file specified in filename, whenever the end-of-file is 
encountered. This function is useful if multiple scripts read data from one file. 



7.5.2.17 File Input/Ouput Function Examples 

The following example illustrates using the functions Fioreadf ield { ) and 
Fioreadf ields ( ) to read one or more fields from a file. Fiodelimiter ( ) is used 
to specify that the field delimiter in the file input file is a comma. 
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char last [20] ; 
char first [20] ; 



Fioopen { " input file" , "r" ) ; 
Fiodelimiter ( "inputf ile" , " , " ) ; 
Fioreadf ield ( " inputf ile" ) ; 
Type ( " %s " , FIOBUFFER) ; 

LeftButtonPress (360, 211) ; 



AppWait (0.06) ; 
WindowRcv( "SfSf Pt M ) ; 

Fioreadf ields ("inputf ile" f 2, last, first); 
Type( " %s" , last) ; 

LeftButtonPress { 3 57 , 2 52 ) ; 



AppWait (0 . 06) ; 
WindowRcv( "SfSfPt" ) ; 

Type( "%s" , first) ; 



The following is a portion of the file inputf ile: 



312890463 
doe, jane 
294028190 
smith, john 
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The following examples show you how to use the rewind functions to reuse data in 
an input file. Notice that Fioautorewind ( ) saves you some programming time 
because you do not have to check to see if you are at the end of the file: 



Fioautorewind ( "info" ) ; 
Fioreadline ( ,l info " ) ; 
Type ( 11 %s " , FIOBUFFER) ; 



OR 



Fioreadline ( " info " ) ; 
if (FIOLEN==-l) { 
Fiorewind ( " info H ) ; 
Fioreadl ine ( " info " ) ; 
} 

Type ( " %s " , FIOBUFFER) ; 



7,5.3 Pacing Functions 

EMPOWER/CS allows you to insert three functions into your script file for 
controlling the pace of the script These pacing functions cause the script to pause 
long enough to make the script send transactions to the SUT at a predetermined 
throughput. Typically used in a loop, these functions may be nested to permit 
controlled throughput of transactions within a larger transaction. 

Each of the pacing functions accepts an argument naming the pace and defining 
the speed of the pace. 

Paceconstant ( ) causes transactions to be submitted at a constant throughput The 
second argument to Paceconstant ( ) defines the number of seconds that the 
script should take since the last call to Paceconstant ( ) . The first call to a pacing 
function does not delay; it is used as a starting point for the subsequent calls. For 
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this reason, the first call to a pacing function is often made with arguments of 0 to 
define the speed. 

Paceunif orm ( ) and Pacetne ( ) control throughput but do not do so at a constant 
rate. The functions have an average throughput that will be maintained, but 
submission of transactions occurs at frequencies other than that defined by a 
constant distribution. 

Paceunif orm ( ) accepts two arguments to identify the speed of the pace - a 
minimum delay and a maximum delay. The average of the two will be maintained 
during sustained execution of the script Each time Paceuniform( ) is executed, it 
will delay for a number of seconds since the last execution, where the number is 
taken from a uniform distribution between the minimum and maximum values. For 
example, if Paceunif orm ( "query" , 8.0, 12 . 0) is used in a script, a sequence 
of 9, 11, 8, 10, and 12 second delays is possible (assuming the query has a response 
time of zero seconds.) The average of the delays is still ten seconds. 
Paceunif orm ( ) will select the values for delay accurate to l/100th of a second, so 
9.27 seconds is a possible value. 

Pacetne { ) accepts three arguments to identify the speed of the pace - a minimum, 
average and a maximum delay. The average will be maintained during sustained 
execution of the script Each time Pacetne ( ) is executed, it will delay for a number 
of seconds since the last execution, where the number is taken from a truncated, 
negative exponential distribution defined by the three values. In a typical such 
distribution, the average is relatively close to the minimum. For example, if 
Pacetne { "query" , 7.0, 10.0, 20.0) is used in a script, a sequence of 7, 8, 10, 
and 15 second delays is possible. The average of the delays is still ten seconds. 
Pacetne ( ) will select the values for delay accurate to l/10th of a second, so 9.2 
seconds is a possible value. 
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7.5.4 Advanced Clse of Script Variables 

Five EMPOWER/CS functions exist that allow you to manipulate script variables. 
They are CmpVar { ) , GetVar { ) , GetlntVar ( ) , SetVar { ) , SetlntVar ( ) . These 
functions allow you to test, update, read, and compare variables. 

You may insert the CmpVar ( ) function into your script to compare a variable from a 
SQL statement to a specified value. The syntax for this function is: 

CmpVar (curnum, var, value); 

This function determines if the specified variable, var, in the current row is equal 
to the value specified in the value parameter. The address of the variable must be 
passed to CmpVar ( ) . 



This function could be used for fetching records until a certain value is returned. 
An example of this function follows: 



Parse {CUR1, "select ename 


from employee_table M ) ; 


Define (CURD "1", STRING, 


50); 


Exec (CURD ; 




Dbset(CURl, FETCHSIZE, 1) 




while (CmpVar (CUR1, "1", 


"Smith" ) != 0) { 


Fetch (CURD ; 




GetNextRow (CUR1 ) ; 





You can insert the GetVar ( ) or GetlntVar ( } functions into your script to return 
the current value of a specified variable (either the name or the position) in the 
SQL statement GetVar ( ) is used for string variables and GetlntVar ( ) is used for 
integer variables. These functions should be inserted into the script after the 
Fetch () and GetNextRowO functions. 
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The following example demonstrates using the Getvar ( ) function within a script: 



char * empname , * empno ; 



Parse{CURl, "select ename, empno from employee_ table" ) ; 

Define (CUR1, "1", STRING , 50); 
Define (CUR1, "2", INT, 4); 

Exec (CUR1) ; 

DbseUCURl, FETCHSIZE, 1) ; 
while (Fetch(CURl) != 0) { 

GetNextRow(CURl) ; 

empname=GetVar ( CUR1 , " 1 " ) ; 

print f ( "empname is %s\n" , empname); 

empno=Ge tVar ( CUR1 , " 2 " ) ; 

print f ( "empno is %d\n" , Mint *) empno); 

} 



The SetVarO and SetintVarU functions assign a new value to a specified 
variable. The syntax for these functions follows: 

SetVar (curnum, var, value); 
SetlntVar (curnuni, var, value) ; 

The new value for the variable, var, is assigned in the parameter value. These 
functions could be inserted into the script before an Exec ( ) function or after the 
GetNextRowO or GetVar ( ) functions. 
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The following example demonstrates using SetintVar ( } in a script: 



int empno, deptno, i; 



Parse {CUR1, "select ename from employee_table where empno=:empno 
and deptno= : deptno" ) ; 



Data(CURl, "23 | 20 " ) ; 

empno=GetIntVar (CURl , "1"}; 
deptno^GetlntVar (CURl, M 2) ; 

/* keep executing above parse statement changing the empno 

every time */ 

for (i=0; i<5; i++) { 

empno=empno+i ; 

SetintVar (CUR1 , "2 " , empno) ; 

Exec (CURD ; 

if (Fetch(CURl) != 0) 



print f ( "empno %d is in deptno %d\n" , empno, deptno); 



BindptCURl, 1, INT, 4) ; 
Bindp(CURl, 2, INT, 4) ; 



/* pos 1 is : empno */ 
/* pos 2 is : deptno */ 



else 



printft "empno %d is not in deptno %d\n" r empno, 



deptno) ; 
} 
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7.5.5 Looping 

EMPOWER/CS scripts may be modified to contain loops controlled by the standard 
C language for and while statements. You can use a loop to emulate hour long 
activity instead of having to capture activity for an hour. The for statement 
executes a set of EMPOWER/CS functions a fixed number of times. The while 
statement executes a set of EMPOWER/CS functions as long as a given condition 
is satisfied. 

You must insert loops very carefully if you plan to execute scripts in both Non- 
Display and Display modes. You must be sure to encompass all relevant functions 
in the loop for Non-Display and Display script execution. For example, you must 
include all relevant button presses within the loop so that the correct sequence of 
buttons will be activated during script execution in Display mode. 

For your convenience, you should insert a comment or function in the script to 
mark where you wish to begin and/or end looping. 



733.1 Looping with the For Statement 

Executing a loop a certain number of times in a script is accomplished with the for 
statement The syntax of the for statement is: 

for (initial; condition; step) 
{ 

/* body of the loop */ 

} 

The parameter initial generally contains the initial assignment of a looping 
variable. The parameter condition specifies the condition under which looping 
should continue. This condition is evaluated every time the loop is about to be 
entered. The parameter step generally specifies the increment or decrement of the 
looping variable. Note that the body of the loop is contained between braces, { }. 
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7.5.5.2 Looping with the While Statement 

The while statement is used to execute a loop in an EMPOWER/CS script as long 
as a given condition is satisfied. The syntax is listed below: 

while (condition) 
{ 

/* body of the loop */ 

} 

Each time the loop is entered, the condition specified in the parameter condition 
is tested. If the condition is met, the loop is executed. If not, script execution 
continues past the loop. 

The following example demonstrates a common while loop used within 
EMPOWER/CS scripts: 

Fetch (CURl) ; 

while (GetNext Row (CURl ) ! =NOMOREROWS ) ; 
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8.0 EMPOWER/CS Tools 

EMPOWER/CS offers four Windows features under the Tools icon. These Tools 
are XY, Modules, Transfer, and Tree. 

When you activate Tools in the EMPOWER/CS window, the following window 
opens: 



Empower/CS 




8.1 XY 

If you wish to add or change mouse button events (i.e., Lef tButtonDown ( } , 
Lef tButtonUp ( ) , RightDblPress { ) , etc.) in the script file, you will need to know 
the on screen xy coordinates of the locations that are to be activated. The XY tool 
helps you to locate on screen xy coordinates of the PC mouse. 
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Activate the XY pushbutton. The following window appears displaying the current 
xy coordinates of your mouse: 



B XY 



File Help 
( 99,134 ) 

Trace M 



The Trace option of this tool follows your mouse movements listing the on screen 
xy coordinates as the mouse moves. If you de-select Trace, you can type a number 
in the left field that will move the mouse to that x position on screen. If you tab to 
the next field, you can enter a y position that will move the mouse to that y position. 
As you type each number, the mouse will move to the specified position. 

Select Exit from the File menu to close this tool. 



8.2 Modules 

Select the Modules button to activate the following window: 
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Modules 



c:\windows\progman.exe (1) 
c:\windows\system\comm.drv (26} 
c:\wi n d o ws\sy ste m\co m m d I g . d 1 1 (1 3} 
c:\windows\systern\coure.fon (1) 
c:\windows\system\gdi.exe (26) 
c:\wi n d o ws\sy ste rn\key b o a rd . d rv (2 8) 
c:\wi n d o ws\sy ste m\krn 1 3 8 6 . exe (3 4) 



OK 



Update 



This tool alphabetically lists all the processes currently running in Windows. The 
number listed in parentheses indicates how many instances of the process are 
running. Update updates all process information. 

The Modules tool can be used for debugging. For example, if you encountered an 
error when trying to Capture client/ server activity, you could use Modules to verify 
that winsock.dll is installed on your PC 



Select OK to exit this tool. 



8.3 Transfer 

The Transfer tool allows' you to transfer files manually from the PC to the UNIX 
script driven 

Select the Transfer pushbutton in the Tools window. The following window will 
open: 
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Transfer 



File 



exl.c 



Type ®Ascii O Binary 



Host 
Username 
Password 
Remote Directory 



indy 



john 



/temp 



OK 



Cancel 



Browse. 



Enter the complete name of the script or data file you wish to transfer and specify 
in what form you wish to transfer the file, either as ASCII or Binary. 

In DOS files, an end-of-line includes a carriage return and a linefeed whereas in 
UNIX an end-of-line requires only a linefeed. Transferring a file as ASCII translates 
the carriage return/linefeed combinations in a DOS file to the single linefeed 
required in UNIX. 

If you specify Binary, the file is transferred without character translations. 
Therefore, you should specify Binary for transferring files in which data can not be 
altered and all characters are required for the file (i.e., images). 

If large amounts of data (i.e., images, large text files, etc.) are input to the database 
during Capture, such data is inserted into separate data files. If you are transferring 
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a script that has data files, you must transfer the associated data files separately in 
Binary mode. Scripts should be transferred as ASCII files. 

If you need to locate a file, select the Browse pushbutton in the Transfer window to 
browse all available directories. 



The following Browse window will open: 



File Name: 



diffem.c 

k.c 

r.c 



List Files of Type: 
Scripts(*.c) 



Select File(s) 



Directories: 
c:\empower\cs\t 



&c:\ 

& empower 

cs 



Drives: 
^ c: 



OK 



Cancel 



Network. 



□ Read Only 



In this window, you may specify or search through all available directories, files, and 
disk drives. You may select multiple files from a specific directory. When you have 
located all needed files, choose OK or Cancel as appropriate to return to the 
Transfer window. 



After specifying a file, you should enter the Host name (the UNIX driver), the 
appropriate Username and Password, and the Remote Directory (on the UNIX 
driver) where you wish to transfer the script file. 

In the Transfer window, select OK to transfer the specified file to the UNIX driver 
machine. 
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If the script .c file already exists on the UNIX driver, you will receive the following 
message: 



Warning 






OK! 




Cancel 



Choose OK or Cancel as appropriate. 



8.4 Tree 

The Tree tool allows you to list the tree structure for a MS Windows pushbutton, 
such as OK, Cancel, Yes, No, etc. 

This toot can be used if you wish to manually insert or change a ButtonPusht ) 
function. It allows you to determine the tree structure for the ButtonPush { ) 
function's str parameter. 



8.4.1 The Tree Structure 

The MS Windows tree structure is based on a heirarchy of windows where each 
window that is accessed from a primary, or parent window, is a child of that parent 
For instance, each window or pushbutton that is activated from another window is a 
child of the window it opens from. If two or more equal level windows are 
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accessible from a parent window, they are children of that parent window and 
siblings of each other. 

The following diagram demonstrates this structure: 



2nd child ofW1 




3rd child of C1 



The Tree tool lists a tree structure from right to left, from child to parent, where the 
right-most item is the name of the button or window you selected. If one of the 
windows or the pushbutton has no title, something like ,T #d" will be listed to 
indicate the window or pushbutton is a certain numbered child of the preceding 
parent window. 

Note: In some rare cases, applications are designed where a window requires its 
sibling window to also be its parent in which case something like "#s1" may be 
listed in the structure. 

A tree structure from the above diagram could look like: W1(#c1|#c2. In this 
example, #c2 is the second child of the first child (#c1) of the window W1. 
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In the following tree structure, Tools|WindowTree|Cancel, Cancel is the button 
contained in the window WindowTree which is a child of the Tools window. 



8.4.2 Using the Tree Tool 



Select the Tree button from the Tools window which opens the following window: 



Window Tree 



[Tree 



Cancel 



Activate the Tree button. The mouse pointer will turn into a large arrow. 

With this new pointer, select the button for which you wish to list the Tree 
structure. This tree structure is listed in a particular heirarchy as explained above in 
Section 8.4.1. 

As an example, obtain the Tree structure for the Cancel button, by selecting Tree. 
Then, select Cancel in the WindowTree window as shown below; 

The following structure will appear in the Window Tree window: 

Tools|Window Tree|Cancel 



When you have obtained all needed tree structures, select the Cancel button or 
Close from the Window Tree window's System menu. 
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1.0 Introduction 

In the Script Development manual, you learned how to create sophisticated scripts 
for emulating user activity on your system under test. This manual guides you 
through the execution of multi-user tests with EMPOWER, EMPOWER/X, or 
EMPOWER/CS. 

For multi-user testing, you may execute several scripts simultaneously to apply a 
workload to the system under test. Individual scripts may be duplicated to represent 
multiple users performing similar activities, and different scripts may be mixed to 
emulate a complex set of user and application activity. 



1.1 Multi-CIser Testing Tools 

Multi-user testing is conducted with the following tools: Mix, Extract, Report, Draw, 
Monitor, and Global Variables (GV). 

Mix emulates an actual benchmark environment by executing multiple scripts. It 
uses a script table and, optionally, a command file to specify the number of 
emulated users, the name of each executed script, each user's communication line, 
the delay time between the start of each script, and the termination condition of the 
emulation. Mix executes compiled scripts and each executing script produces a log 
file used to prepare resulting reports. 

Generating performance reports is accomplished in two steps. The Extract tool 
parses the log file of each script and records response time information in a set of 
flat ASCII files that are used as input for the Report tool. (You also may choose to 
generate reports from your own statistical or graphics programs.) 

Report reads the ASCII files generated by Extract and produces statistical reports 
describing response time and system throughput. The reports can be generated to 
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conform to reporting specifications often defined in Government Services 
Administration benchmarking requirements (see GSA FPR 1-4.11). 

After you have generated performance reports for your multi-user emulation, Draw 
will accept one or more reports to produce bar charts that depict relationships 
among performance results. These relationships can summarize a single multi-user 
test or a series of multi-user tests in which each test contains a different user level 
or system configuration. 

The Monitor modules display critical information about emulated users during multi- 
user benchmarks. A single ASCII terminal, X terminal, or workstation is used to 
monitor response times, control script execution, track and correct script errors and 
timeouts, and present benchmark progress. Information is provided in logically 
grouped views that may be sorted on any field in the view. With the Monitor tool, 
you can identify and debug problem scripts, verify system load, and take a 
snapshot of user activity during a system bottleneck. Commands are provided to 
suspend, resume, and kill scripts during a multi-user test 

The Global Variables tool, EMPOWER/GV provides advanced control over multi- 
user emulations by creating and controlling global variables that are shared among 
executing scripts. Variables can be defined to direct scripts to terminate gracefully 
when they run an indefinite process. They can be used as a counter for scripts that 
must perform a fixed amount of work before terminating. Variables also may be 
used to synchronize the execution of multiple scripts. The elements of 
EMPOWER/GV include commands and functions which control access to a variable; 
read, update, or test values of variables; or control a shared memory segment. 



1.2 User's Guide Organization 

General use information and specific technical reference material for operating the 
PERFORMIX load testing products are provided in several manuals. Examples have 
been provided for clarity. 
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This manual, Multi-User Testing, is divided into the following sections: 

Section 1: Provides an introduction to multi-user testing 

Section 2: Describes the Mix tool which combines scripts to develop 
complete emulations of systems or applications to be 
tested 

Section 3: Describes the Extract tool which collects performance data 
from log files of executed scripts 

Section 4: Describes the Report tool which produces statistical 
reports of results of multi-user performance tests 

Section 5: Describes the Draw tool which graphically displays results 
of multi-user performance tests 

Section 6: Describes the Monitor tool which displays critical 

information about scripts during execution. It also can 
control script execution 

Note: This manual is used for the PERFORMIX Inc. products EMPOWER, 
EMPOWER/X, and EMPOWER/CS. The EMPOWER, EMPOWER/X, and 
EMPOWER/CS tools for script development are all maintained separately. 
However, the tools for multi-user testing, as described in this manual, are common 
among the EMPOWER products. Some commands and situations may apply only to 
one of the products. These instances are specifically noted within the text. 



You may notice different version numbers for any one of the multi-user tools. If 
you have purchased two or more EMPOWER products, the version number for the 
multi-user testing tools will correspond to one of the EMPOWER products 
purchased 
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13 User's Guide Conventions 

The conventions followed in this User's Guide are listed below: 
Regular Font Used for all regular body text 

Mono-spaced Font Used for all command, function, and file names; for all 

examples; and, generally, for any computer-generated text 

Bold Mono-spaced Font In examples, represents entries made by the 

EMPOWER, EMPOWER/X, or EMPOWER/CS user 

[-p port] In command syntaxes, text within brackets represents 

optional command parameters 

gv_stat [name | -s] Vertical lines ( | ) separate command parameters 

Within scripts, the ellipsis marks indicate some script 
content was left out for brevity 

Beginf unction ( ) Parentheses are included with script functions mentioned 

in regular body text For most functions, one or more 
parameters will be listed in the parentheses 

Endscenario ( ) EMPOWER/CS script functions use initial capitalization 

extract EMPOWER/CS command names use all lower case 

letters 

Mix When an EMPOWER, EMPOWER/X, or EMPOWER/CS 

tool is mentioned within regular body text, it is shown in 
regular font with initial capitalization 

The term "SUT" refers to your system under test 
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2.0 Mix 

Complete, thorough emulations must stress a system under test (SUT) to verify that 
it can handle predicted workloads. Therefore, EMPOWER, EMPOWER/X, and 
EMPOWER/CS must be able to emulate various users operating multiple terminals 
connected to the SUT (or for EMPOWER/CS, multiple PCs connected to the 
server). 

A goal for realistic load testing is to replace the environment of the SUT. This goal 
is accomplished with the Mix tool which combines multiple scripts to simulate an 
actual load on the system. Individual scripts may be executed in parallel by multiple 
emulated users, and different scripts may be mixed to represent complex user and 
application activity. To simulate the entire system environment, Mix simultaneously 
controls the complete mix of scripts. 



2.1 The Mix Table 

Specifications for a multi-user emulation are provided in a mix table which 
identifies users and specifies the script each user will emulate. Each line in the 
table directs the execution of a single script, and the size of the mix table is 
unlimited In the following example mix table, we will emulate six users working 
simultaneously. An example for each EMPOWER product is included. 



userl, query telnet :sut logl 

user2 , report tty8 log2 

user3 , x query x query log3 

user4, xquery -d serverhost:0 xquery log4 

user5, csquery log5 

user6, csupdate log6 



The first item you enter in a mix table is the script ID which represents the 
emulated user name. The script ID is used by the Mix and Monitor tools to identify 
each script individually. Following the user name and comma in each line is the 
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script execution command which includes the executable script file name and any 
valid script execution options. These options are fully defined in the Compiled 
Script Execution sections of the EMPOWER Script Development, EMPOWER/X 
Script Development, and EMPOWER/CS Script Development manuals. 



While executing scripts, Mix will create log files for each script which are named by 
adding a . 1 extension to the script ID. The default logs files for the following 
example scripts will be userl . 1, user2 . 1, user3 . 1, and user4 . 1: 



userl , 


scriptl 


telnet : sut 


user2 , 


scriptl 


telnet :sut 


user3 , 


script2 


telnet : sut 


user4 , 


script2 


telnet : sut 



If e_port equals telnet: sut, you do not need to specify telnet : sut. The above 
Mix table could look like the following. 



userl, scriptl 

user2 , scriptl 

user3, script2 

user4, script2 



If you want to name the script log files different from the script id, you must type 
the names after the specified port 



Example: 



userl, 


scriptl 


telnet : sut 


logl 


user2 , 


scriptl 


telnet : sut 


log2 


user3 , 


script2 


telnet : sut 


log3 


user4 , 


script2 


telnet : sut 


log4 



If you wish to pass your own arguments to the script, you are required to specify 
the port and log for each script. 
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Example: 



userl, 


scriptl 


telnet 


sut 


logl 


userOOl 


passOOl 


user2 , 


scriptl 


telnet 


sut 


log2 


user002 


pass002 


user3 , 


script2 


telnet 


sut 


log3 


user003 


pass003 


user4, 


script2 


telnet 


sut 


log4 


user004 


pass004 



You may want a single emulated user to execute several scripts consecutively, 
which is achieved by replacing the user name for subsequent scripts with a "+", as 
shown in the following example. You will need to specify different log names or 
subsequent scripts will overwrite the default log files of the previous script 
execution. 



ul, query telnet: sut logla 
+ report telnet: sut loglb 
+ modify telnet: sut logic 



In the above example, one ASCII terminal user executes the script called query, 
then the script called report, then the script called modify. The results are saved in 
the Mix log files logla, loglb, and logic, respectively. 

A similar process applies to an X terminal user in the following example: 



u2, report report log2a 
+ query query log2b 
+ modify modify log2c 



For a PC user: 



u3 , report log3a 
+ query log3b 
+ modify log3c 



To simulate the time a user might spend between different operations (different 
scripts), you may add a "sleep" period before executing another script. 
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This activity is performed by adding a sleep parameter after the + in the mix table 
entry: 



ul, query telnet :sut logla 

+ sleep 5 report telnet :sut loglb 

+ sleep 5 modify telnet : sut logic 



After you have created your Mix table, you must save it as a file to be used later in 
your Mix emulation. The Mix table file name is specified in the use command of 
Mix. Refer to section 2.323 for a description of the use command. 



2.2 Mix Syntax 



Once the mix table has been created, the mix command is used to execute scripts. 
The syntax of the mix command is given in the following usage message. You may 
access the usage screen by entering the mix command with a hyphen parameter: 



$ mix - 




EMPOWER 


V3.1.8, Serial#R00000-000, Copyright PERFORMIX , Inc. 1988-95 


Usage : 






mix [-f mixfile [-d]] [-1 log] [-I]|[[-D] [-p port]] 


Options 






-f mixfile Runs MIX in batch mode reading commands from mixfile 




-d Prevents display of MIX session on screen 




-1 log Causes the MIX trace to be stored in log 




-p port Specifies the port Daemon should listen on 


Note: 






MIX runs in interactive mode by default. 




In interactive mode, type ? to obtain more help. 




Use the -f and -d options when running MIX in the background. 




By default, the MIX trace is stored in mix. log. 




Default MIX Daemon port is 7273. 


Examples : 




mix 




mix -f run3user 




mix -f run6user -d & 




mix -1 3user.log 




mix -p 3333 
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2.2.1 Batch Mode 



When Mix runs in interactive mode, you can control execution of the multi-user 
test by entering Mix commands at the mix> prompt on the UNIX script driver 
machine. However, a large test may be time consuming. Therefore, you can 
execute a multi-user test by running Mix in batch mode. In batch mode, Mix will 
read commands from a command file rather than from your terminal. 

Create the command file you wish to use in your emulation and then specify the 
command file name in the -f option's parameter (mix -f cmdfile). Mix will 
terminate when it reaches the end of the command file or when it encounters a 
quit, q, or exit command 

Typically, one command file is generated for each configuration to be tested. For 
example, if you are testing your SUT with one, eight, and thirty-two users, you 
might create three separate command files called luser.cmd, 8user.cmd, and 
32user.cmd that would look like the following: 



note: Any lines in a batch file that start with "# " are assumed to be comments and 
are ignored during script execution. 



luser . cmd: 



8user.cmd: 



32user . cmd: 



use 100 user. tab 
start userOOl 
wait 
quit 



use Suser.tab 
start all 
wait 
quit 



use lOOuser.tab 
start user [001-032] 
wait 
quit 
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2.2.2 Turning Off the Mix Display 

When you execute Mix in batch mode, the output of commands executed from the 
command file is displayed at the UNIX script driver. If you do not want Mix to 
display this output, for example if Mix is running in the background, enter the -d 
option of the mix command 

Example: 

$ mix -d 



2.2.3 The Mix Log 

When Mix executes a mix table, it generates a log of its activities. The Mix log file 
contains all executed Mix commands, the time that each command was executed, 
and a copy of the Mix output If the log file already exists when Mix is run, it will be 
overwritten. 

By default, this log is called mix. log and is saved in the current directory. If you 
wish to specify a different name, use the mix command's -1 option with a 
parameter of the desired log file name. Typical names are luser . log, 8user . log, 
and 32user.log. 
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An example Mix log file is shown below: 



15 


:38 


:27 


.53 


mix> use tab 






15 


:38 


:30 


.47 


mix> set tstart 2 






15 


:38 


:34 


.75 


mix> start all 






15 


: 38 


: 38 


. 06 


[userOl] started 






15 


:38 


:40 


.17 


[user02] started 






15 


:38 


:42 


.17 


[user03] started 






15 


:38 


:44 


.17 


[user04] started 






15 


:38 


:44 


.23 


mix> wait 






16 


:35 


:26 


.36 


userOl terminated 


(3/4) 


running 


16 


:35 


:26 


.36 


user02 terminated 


(2/4) 


running 


16 


:35 


:28 


.44 


user03 terminated 


(1/4) 


running 


16 


:35 


:28 


.44 


user04 terminated 


(0/4) 


running 


16 


:35 


:28 


.45 


no more scripts running 




16 


:35 


:28 


.45 


mix> quit 







2.2.4 Specifying Ports for Mix daemons 

Relevant only to distributed emulations with Mix, the -p option of mix specifies the 
port that Mix daemons should listen on. The default Mix daemon port is 7273. Refer 
to Section 252 for a more detailed explanation of distributed emulations with Mix. 



2.3 Mix Commands 

The Mix tool allows you to control script execution in the mix table by providing 
several Mix commands. Mix is a command interpreter, so it displays its own prompt 
on the UNIX script driver when executed interactively. The Mix commands may be 
entered at this prompt or may be contained in command files for batch execution. 
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2.3.1 ? 



The ? command displays the Mix command help screen: 



$ mix 






EMPOWER 


V3.1.8, Serial#R00000- 


000, Copyright PERFORMIX, Inc. 1988-95 


mix> ? 






command 


syntax 


description 


at 


at n cmd 


run MIX command at n seconds 


close 


close 


forget about entries in last script table used 


connect 


connect host . . . 


connect to MIX daemon on host(s) 


exec 


exec commandfile 


execute file of MIX commands 


get 


get host file . . . 


copy file{s) from host 


kill 


kill all | id . . . 


terminate execution of script (s) 


pause 


pause n 


sleep for n seconds 


put 


put host file . . . 


copy file(s) to host 


quit 


quit 


exit MIX 


exit 


quit 


exit MIX 


red 


red host dir 


change directory on host 


rcrnd 


remd host cmd 


run cmd on host 


resume 


resume all | id ... 


continue execution of suspended scripts 


set 


set [variable value] 


initialize a MIX variable 


signal 


signal all | id . . . 


send signal to script (s) 


start 


start all | id . . . 


begin execution of script (s) 


stat 


stat [-1] tid] 


display script status 


table 


table [-a] name fmt 


make a table using format 


time 


time 


display current time of day 


trap 


trap command 


run command if ! cmd exits with error 


use 


use table 


read script table 


wait 


wait 


pause until all scripts complete 


mix> 







2.3.2 ! 

The ! command executes a shell command from within Mix on the UNIX driver 
machine. Upon completion of the shell command, control returns to Mix and Mix 
displays its prompt 
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Examples: 



mix> Idate 






Thu Oct 6 15 


49:35 


EDT 1995 


mix> !ps 






PID TT STAT 


TIME 


COMMAND 


23917 p2 IW 


0:00 


-sh (sh) 


25302 p2 S 


0:00 


mix 


25311 p2 S 


0:00 


sh -c ps 


25312 p2 R 


0:00 


ps 


mix> 







2.3.3 At 

The at command is used to execute another Mix command at a specified time. The 
syntax of the at command is shown below: 

at n command 

The integer n represents the time to execute the command, and command is the 
Mix command to be executed The time is specified in seconds from the beginning 
of the Mix session. The at command is useful for executing Mix in batch mode. 
For example, the following command will execute the Mix command start all 
one minute (60 seconds) after the Mix session has started 

mix> at 60 start all 

If the at command executes after the specified time has expired, a warning will be 
displayed and the command will execute. The following example Mix session 
shows the use of the at command 30 seconds after the session began: 

mix> at 5 time 

warning: at time has passed 

time: 12:11:05 
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23.4 Close 

The close command ends the use of one mix table before proceeding to another 
mix table. A close command must be used before a second use command is 
entered Refer to section 23.23 for a description of the use command 

Example: 

mix> use tablel 
mix> start all 
mix> wait 
mix> close 
mix> use table2 



2.3,5 Connect 

The connect command is used only when running Mix as a daemon on multiple 
UNIX driver machines. This command connects the specified remote Mix 
daemon(s) to the central Mix session. Refer to Sections 2.5.2 and 2.5.3 for a more 
detailed explanation of distributed emulations with Mix. 



2.3.6 Exec 

The exec command, generally used in interactive mode, directs Mix to retrieve and 
execute a series of commands that are stored in a separate file. This capability is 
helpful for executing a frequently used set of commands without constantly 
retyping them. Notice that the user controlling Mix types only two commands to 
start the test 
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Example: 
The s4 file: 



use 4usertab 
set tstart 2 
set tresume 2 0 
set logdir ./logs 
!date 



The Mix session: 



mix> exec s4 
mix> use 4usertab 
mix> set tstart 2 
mix> set tresume 20 
mix> set logdir ./logs 
inix> ! date 

Thu Oct 6 15:59:24 EDT 1995 
mix> start all 



2.3.7 Get 



The get command is used when ninning Mix as a daemon on multiple UNIX script 
driver machines. This command copies a specified file(s) from a specified remote 
UNIX driver machine to the primary UNIX driver machine. Refer to Section 2.53 
for a more detailed explanation. 



23.8 Help 

The help command displays the help menu. This command performs the same 
action as "?" . 



EMPOWER/CS Vl.0.1 



2-11 

Copyright PERFORMIX, Inc © 1995 



User's Guide— Multi-User Testing 



2.3.9 Kill 

The kill command terminates execution of one or more scripts. You can specify 
scripts to be killed by their script ids in the first field of the script file entry. The 
kill command is followed either by the script ids or by the key word all, which 
will terminate the execution of all scripts currently executing. 



Example: 



mix> 


use tablel 


mix> 


start all 


mix> 


pause 600 


mix> 


kill all 


mix> 


wait 


mix> 


quit 



The kill command allows the specification of a range. For example, to kill the 
scripts userOl, user02, user07, the following command is used 

mix> kill user[01-07] 

To specify multiple scripts that are not continuous, use the command specification 
shown in the following example: 

rnix> kill user [ 02, 04, 12] 

Note: The specification of ranges in Mix does not work exactly like the 
specification of ranges in the UNIX shell. The following UNIX shell command would 
list chapl through chapS and chapO: 

$ Is chap[l-50] 

Range specification in the UNIX shell accepts only single characters. 
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23.10 Pause 

The pause command causes Mix to delay for a period of seconds. Pause often is 
used in command files when an emulation must execute for a specified time 
before terminating. Pause can be used when a large number of scripts require time 
to log in and suspend themselves before all scripts can be resumed. 



Example: 



mix> 


use table9 


mix> 


start all 


mix> 


pause 20 


mix> 


resume all 


mix> 


wait 


mix> 


quit 



23.11 Put 

The put command is used when running Mix as a daemon on multiple UNIX script 
driver machines. This command copies a specified file(s) from the primary UNIX 
driver machine to the specified remote machine. Refer to Section 2.53 for a more 
detailed explanation of distributed emulations with Mix. 



2.3.12 Quit 

The quit command causes Mix to terminate. If scripts are executing, Mix will ask 
for verification. If you decide to quit while scripts are executing, the scripts will 
continue until they terminate themselves. If Mix is executed in batch mode, the 
quit command will not ask for confirmation. (Note; You can also enter q or exit 
which function exactly as quit.) 
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Example: 

mix> quit 
$ 



2.3.13 Red 

The red command is used when running Mix as a daemon on multiple UNIX script 
driver machines. This command causes the Mix daemon on the specified remote 
UNIX driver machine to change to a specified directory. Refer to Section 2.53 for a 
more detailed explanation of distributed emulations with Mix. 



2.3.14 Rcmd 

The rcmd command is used when running Mix as a daemon on multiple UNIX script 
driver machines. This command executes a specified command on a specified 
UNIX driver machine. Refer to Section 2.53 for a more detailed explanation. 



2.3.15 Resume 

The resume command causes Mix to resume suspended scripts. The resume 
command must be followed by a list of identifiers or the key word all which 
resumes all scripts. 

A script execution is suspended when it executes the suspend ( ) function. The 
Suspend ( ) function is useful for multi-user emulations that require all users to be 
logged into the SUT before transactions can be executed or response times can be 
measured. 
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When resuming more than one script, each script will resume after a delay interval 
which is determined by the value of the tresume variable. The default tresume 
value is five seconds. To change the value of tresume, use the Mix set command 



Example: 



mix> 


use tablel 




mix> 


set TRESUME 


10 


mix> 


start userl 


user2 user3 


mix> 


pause 45 




mix> 


resume all 




mix> 


wait 




mix> 


quit 





The resume command allows the specification of a range. For example, to resume 
the scripts userOl, user02, user07, the following command is used 

mix> resume user [01-07] 

To specify multiple scripts that are not continuous, use the command specification 
shown in the following example: 

mix> resume user [ 02 f 04 , 12] 



23.16 Set 

The set command defines values for the Mix variables. It is followed by the name 
of the variable— tstart, tresume, tsignal, logdir, table, or continue— and 
the new value of the variable. If you enter the set command without any 
parameters, Mix will display the current value of all variables. 

tstart controls the delay between starting scripts, tresume controls the delay 
when resuming scripts, tsignal controls the delay between signaling scripts. 
logdir defines the directory where log files of scripts to be executed are stored 
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table indicates the mix table that will be used for the session, continue has two 
values (on or off) that indicate whether or not continuation scripts will be executed. 
(Continuation scripts begin with V in the Mix table.) All variables are recognized in 
lower case letters, for example, tstart and tresume. 

The default values of tstart and tresume are five seconds and tsignal is zero 
seconds. If you prefer, you can specify these values as floating point numbers 
which allows you to start or resume scripts a half-second apart, one-and-a-quarter 
seconds apart, etc. The default value of logdir is the current directory, table has 
no default, and the default for continue is "on". 



Examples: 



mix> use 4 usertab 
mix> set tstart 2 
mix> set tresume 10 
mix> set logdir ./logs 

mix> set 
TSTART 2.00 
TRESUME 10.00 
TSIGNAL 0.00 
LOGDIR ./logs 
TABLE 4usertab 
CONTINUE on 
mix> 



2.3.17 Signal 

The Mix signal command sends a signal to a script to control execution. For 
example, a signal command can be used with the file input/output routines to 
read type rate values from another file. The script must include a signal { ) 
function to specify an action to take when the script receives the signal. If the script 
does not include a signal ( ) function, the signal command will be ignored 
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The syntax of the signal command is: 



signal scriptid [ . . . ] 



scriptid specifies a script where the signal should be sent The parameter of 
scriptid may be "all", in which case the signal is sent to all scripts. 

The following example shows a portion of a script that uses the signal { ) function. 
When the Mix user enters a signal command, the type rate will be read from a 
file: 



type change { ) 
{ 



int 1 ; 



F i or ewind(" /tmp/typerate" ) ; /* go to beginning of file */ 
Fioreadline ( " /tmp/typerate" ) ; /* read line in */ 



if (FIOLEN > 0) { 

i=atoi (FIOBUFFER) ; 
if(i > 0) 

Typerate (i) ; 

else 

Signal (IGNORE) 

} 

} 

Empower ( ar gc , ar gv ) 
int argc; 
char **argv; 
{ 

Thinkunif orm (1,2.5); 
Timeout (300, EXIT) ; 
Signal (typechange) ; 
Beginscenario ( " shell 11 ) 
/* ... 

rest of script 
... */ 

Endscenario ( "shell" ) ; 



/* if no error */ 

/* convert value to int */ 

/* set the new type rate */ 

/* ignore further signals */ 



/* set the Signal handler */ 



When this script executes, the type rate initially is set to the default of zero 
characters per second The first time the Mix signal command is entered at the 
UNIX script driver, the value in the file /tmp/typerate is read and, if the value is 
not zero, the type rate is set to the specified value. This process repeats every time 
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the signal command is entered until the value read from the file is zero. At that 
point, all subsequent signals are ignored. 



23.18 Start 

The start command executes one or more scripts. To begin executing one or 
more scripts, enter the start command followed by the script ids from the mix 
table. To start all scripts in the mix table, enter the start command followed by the 
key word all. 

When starting multiple scripts, each script will begin after a delay determined by 
the tstart variable. 

Examples: 



mix> set TSTART 10 

mix> start userl user2 user3 

[userl] started 
[user2] started 
[user3] started 



The start command allows specification of a range. For example, to start the 
scripts userOl, user02, user07, enter the following command 

mix> start user [01-07] 

To specify multiple scripts that are not continuous, such as user02, user04, and 
userl2, use the following command format 

mix> start user [02, 04, 12] 



EMPOWER/CS Vl.O.1 



2-18 

Copyright PERFORMIX, Inc. © 1995 



User's Guide— Multi-User Testing 



2.3.19 Stat 



The stat command displays the status of executing scripts. An asterisk (*) 
following a user name indicates that the script is executing. In the following 
example, three scripts were read in the mix table and only user 2 's script is 
running. 

Example: 

mix> stat 

userl user2* user3 

The -1 option of the stat command displays more detailed status in four columns. 
The column headings are script_id, process_id, sleep, and script. 
Script_id is the user name defined in the mix table. Process_id is the process 
identifier assigned by the operating system for the script. The process_id will be 
-1 if a script is not executing, sleep is the time a script will delay before it begins 
execution. Script is the script to be executed including its arguments. 

Examples: 



mix> stat -1 

script_id process_id sleep script 



uOl -1 
u02 23 
u03 -1 



0 exairplel telnet : sut userl 
0 exarrple2 telnet: sut user2 
0 exairple2 telnet: sut user3 



suitirery: 1/3 running 
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2.3.20 Table 

The Mix command table builds a mix table from within Mix, which is useful for 
building large mix tables. The syntax of the table command is: 

table filename argl arg2 . . . argn 

The parameter filename specifies the name of the new mix table, and the 
arguments argl through argn are entries for the Mix table columns. 

The table command is most useful when used with a range specification, as 
shown in the following example: 



mbo table mix. tab user[01-50], script tty[01-50] user [01-50] .1 

This command would produce the following mix table: 



userOl , 


script 


ttyOl 


userOl . 1 


user02 , 


script 


tty02 


user02.1 


user03 , 


script 


tty03 


user03 . 1 


userSO , 


script 


ttyBO 


userSO . 1 



2.3.21 Time 

The time command displays the current time 

Example: 

mix> time 
time: 16:09:51 
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2.3.22 Trap 

The Mix shell escape command ( i ) is used to escape Mix temporarily to execute 
shell commands. The Mix trap command specifies an action to be taken if the 
executed shell command fails, or returns a non-zero exit status. 

The syntax of the trap command is: 

trap cmd 

The parameter cmd specifies the action to be taken which can be "exit", "continue", 
or any valid Mix command (including another shell escape command). For example, 
when a shell escape command returns a non-zero exit status, Mix will exit if the 
value of cmd is "exit"; or it will continue executing if the value is "continue". The 
default trap condition is "continue". 

The trap command can halt execution of Mix, or it can test and reset any function 
of the emulation environment. This command is useful for executing Mix in batch 
mode when a shell escape command in the Mix batch file is critical to the execution 
of the test 

If the shell escape command fails during batch execution, you may not notice an 
error or be able to end the Mix session before your test is flawed. For example, if 
the test executes after the shell escape command fails, the false test start could 
update a database incorrectly which must be rebuilt prior to executing a successful 
test By using the trap command set at "exit", you can avoid such an inconvenience. 

In the following example Mix session, the trap condition is set to "continue " a shell 
escape command returns an error, and the Mix session continues: 



mix> trap continue 

mix> use mixtab 

mix> set tstart 2 

mix> Isetupfile 

sh: setupfile: not found 

mix> start all 
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Now the same example will be executed with the trap condition set to "exit": 



mix> trap exit 

mix> use mix tab 

mix> set tstart 2 

mix> isetupfile 

sh: setupfile: not found 

$ 



Toggling the trap condition between "continue" and "exit" is sometimes useful 
during a Mix batch execution. Certain shell escape commands may be critical to test 
execution and if they malfunction, you should exit the test to make appropriate 
changes. Other shell escape commands may not be important and the test could 
continue even if the command did not execute. The following example Mix batch 
file demonstrates this situation: 



use mixtab 

set tstart 2 

set LOGDIR logs 

!date 

trap exit 

!critical_cmd 

trap continue 

! un import an t_cmd 

start all 

wait 

quit 
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23.23 Use 

The use command identifies the Mix table to be read and used during the test. You 
must enter this command before a start command can execute. 

Example: 

mix> use tablel 
mix> start all 



2.3.24 Wait 

The wait command tells Mix to wait for all scripts to complete before continuing. 
Upon each script's completion, Mix displays a message containing the current time, 
the script identifier associated with the script, and the number of scripts still 
running. 



Example: 



mix> use tablel 






mix> start all 






[userl] started 






[user2] started 






[user3] started 






mix> wait 






userl terminated 


(2/3 


running) 


user2 terminated 


(1/3 


running ) 


user3 terminated 


(0/3 


running ) 


no more scripts running 


mix> 
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2.4 Sample Mix Session 

In the following example, two emulated users will run one script each. Userl will 
execute the script examplel and user2 will execute the script example2. The mix 
table, tablel, will be used by Mix, and the default log file mix. log will be created. 
During Mix execution, we will instruct Mix to use tablel, to display script status, to 
start all scripts, to wait until all scripts have completed, and to quit 



An example of tablel follows: 



userl, examplel -n 1 -d serverhost:0 
user2, example2 -n 2 

The example Mix session is presented below: 


$ mix 




Mix: EMPOWER V3 .1.8, Serial#R00000-000 , Copyright PERFORMIX, Inc. 1988-95 


mix> use tablel 




mix> stat -1 




script_id process_id 


sleep script 


userl -1 


0 examplel -n 1 -d serverhost:0 


user2 -1 


0 example2 -n 2 


summary: 0/2 running 




mix> start all 




[userl] started 




[user2] started 




mix> wait 




userl terminated (1/2 


running ) 


user2 terminated (0/2 


running) 


no more scripts running 


mix> quit 
$ 





Extract and Report typically are executed after a multi-user emulation. The following 
example demonstrates the easiest method for executing the Extract and Report 
commands after the two-user test 

$ extract * . 1 
$ report 
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After executing the Extract and Report commands, your report can be found in the 
file report. STD. 

Sections 3.0 Extract and 4.0 Report fully explain how to operate these multi-user 
tools. 



2.5 Distributed Emulations with Mix 

Some load tests require multiple UNIX driver machines to emulate large numbers 
of users. The mix session on your primary UNIX script driver can connect to and 
control Mix sessions on additional driver machines. The additional mix sessions act 
as "daemons" receiving instructions from the primary UNIX script driver's mix 
session. 

Mixd, the tool used on run-time (or remote) driver machines, communicates with 
the master Mix session on the primary UNIX script driver machine to control 
scripts. The Mix daemons and master Mix session communicate via TCP/IP 
network connections. AH Mix sessions must connect to and communicate through 
the same TCP port number. The default port number is 7273. 



2.5.1 Installing a Run-Time License 

After purchasing the Run-Time option, you will need to install the software on each 
additional UNIX driver machine. To install a Run-Time license, install your 
EMPOWER software from the distribution media onto each run-time machine. 
(Clearly, the run-time machine must be binary compatible with the primary UNIX 
script driver. Refer to Section 3.0 Installation in the Empower Script Development 
manual for complete installation instructions.) Change to the Install directory created 
by reading the EMPOWER tape or diskettes. Run . /eminstall. Follow the 
instructions given by Eminstall for contacting Performix customer support to obtain 
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a password. Make sure you write "Run-Time" on the password request generated 
by Eminstall. 

When you have your installation password, re-run . / eminstall and type the 
password when requested. Eminstall will install the binaries that you read off the 
tape or diskettes. Only mixd, the gv commands, and mon, (or xmon or csmon as 
appropriate) are executable on a Run-Time Licensed machine. You must execute all 
other tools or commands from the primary UNIX script driver machine. 



2.5.2 Methods for Running Multiple Mix Sessions on Remote 

Machines 

After installing Mixd on all of your run-time UNIX driver machines, you may begin a 
Mix session on a machine in three ways. The first method is simply to type mixd at 
the run-time machine. The Mix daemon will begin and will run in the background, 
waiting for instructions from the primary UNIX script driver's Mix session. 

The second method uses a "mixdaemons" file on the primary UNIX script driver to 
start remote Mix sessions automatically. This file should be located in the $ empower 
directory and should contain lines with two fields that are separated by commas. 
The first field is the host name of the run-time machine. The second field is a 
command that will start the Mix daemon on the run-time machine (typically a remote 
shell command such as rsh, rcmd, or remsh). 

The connect command attempts to connect to the Mix daemon on the remote 
UNIX script driver. Whenever a connection is attempted that is not accepted 
immediately (Le., if mixd is not running), the "mixdaemons" file will look for a line 
containing a command to start the Mix daemon. This command then will execute 
and the connection should be successful. 
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An example "mixdaemons" file follows: 



crosby, 


rsh crosby 


/ us r / empower /b in /mixd 


gemini , 


rsh gemini 


/ us r /empower/ bin /mixd 


kitf ox, 


rsh kitfox 


/usr/ empower /bin/mixd 



The third and most advanced method for starting a Mix daemon involves the inetd 
network process daemon. We recommend that you become proficient with the first 
two methods for running multilple UNIX script drivers before proceeding with the 
following method 

A Mix daemon will start automatically whenever the master Mix session connects to 
the run-time machine through the specified TCP port If you use this method, you 
must first specify the communications port to be used by adding the following line 
to the /etc /services file (or local variation) on each machine that will run a Mix 
daemon: 

mixd 7273 /tcp 

You may change the TCP port number to any number greater than 1024, and this 
number must be used for all Mix daemons. The default port number may be 
overridden with the -p option of the Mix or Mixd commands (follow the -p with the 
appropriate port number). This option is necessary only if port number 7273 
already is used in the /etc /services file of any of the UNIX driver machines. 

You must add the following line to the /etc/ inetd. conf file (or local variation) so 
that the inet daemon runs the correct command when the master Mix session 
connects to the specified port 

mixd\t stream\t tcp\t nowait\t root\t/u/erpcwer/bin/rtd^oi/mix^ -I 

In this line, \t represents tab characters. You should replace the directory 
/u/ empower /bin with the directory and bin that includes the EMPOWER 
executables. To ensure that the updated file /etc/ inetd. conf is used, you must 
reboot the machine or a sighup signal must be sent to the inetd process which 
tells inetd to re-read the inetd. conf file. 
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2.5.3 Mix Commands for Distributed Emulations 

The following five commands, listed in the Mix help screen, support distributed 
emulations with Mix (Note: host represents the name of the run-time UNIX driver 
machine running a Mix daemon): 



Command Syntax 



Description 



connect 

get 

put 

red 

rand 



connect host . 
get host file 
put host file 
red host dir 
rand host and 



connect to remote Mix daemon(s) 
copy file(s) from host 
copy file(s) to host 
change directory on host 
run command on host 



connect 



get 



Connects the specified remote Mix daemon(s) to the 
central Mix session 

Copies the specified file(s) from the specified remote 
UNIX driver machine to the primary UNIX script driver 



put Copies the specified file(s) from the primary UNIX script 

driver machine to the specified remote UNIX driver 
machine 

(Note: The put and get commands are useful for copying scripts and log files 
to and from run-time UNIX driver machines.) 

red Causes the Mix daemon on the specified remote UNIX 

driver machine to change to the specified directory 

remd Executes the specified command on the specified UNIX 

driver machine 



Before executing scripts on a remote (run-time) UNIX script driver machine, you 
should instruct the Mix daemon on that machine (by using the red command) to 
change to a directory where you can create files. A common scenario is to 
"connect" to a run-time machine, "red" to a test directory on the machine, "put" the 
script binaries onto the machine, run the test, and after the test has executed, "get" 
the log files from the run-time machine. 
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2.5.4 Executing a Distributed Emulation with Mix 

When executing a distributed emulation multiple UNIX script driver machines, you 
can specify the scripts to be run on each run-time UNIX driver in two ways. 

You can include the run-time machine's host name in the Mix table: 



tinker@rteA, dbquery telnet :sut tinker 
evers@rteB, dbquery telnet : sut evers 
chance@rteC, dbquery telnet: sut chance 



Then, start the users on the specified machines by using one of the following Mix 
start commands: 



y5 $ start all 

0" $ start tinker evers chance 



With the second method, you specify the run-time machine's host name in the Mix 
start command as in the following examples: 

$ start QrteA all 

$ start @rteA tinker evers chance 

$ start allQrteA 

$ start tinkerGrteA evers@rteB chanceGrteC 



Note: You can override a scriptid assigned to the run-time host in the Mix table by 
specifying a different run-time host in the Mix start command. This capability 
would be useful for redistributing users without editing the Mix table. 

You should connect to each run-time Mix daemon explicitly by using the Mix 
connect command at the beginning of the Mix session. Using this command 
prevents having to restart the entire test if a Mix daemon does not start 

A Mix command file is presented below that includes common steps required to 
execute a distributed emulation using a run-time UNIX driver machine. This 
example command file is executed by using the Mix option, -f filename. 
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Our example Mix table follows: 



user01@hosta, ./script telnet :hostc 
user02@hostb, ./script telnet :hostc 
user03, ./script telnet :hostc 
user04@hosta, ./script telnet :hostc 
user05@hostb, ./script telnet :hostc 
user06, ./script telnet :hostc 



This table lists entries for starting scripts on two remote UNIX driver machines and 
on the primary UNIX script driver. (Note: Including /" in script names may be 
necessary so that the Mix daemon can find the script. ) 

The mix . cmd file follows: 



# the "use <table>" command will automatically 

# connect to all hosts named in the table, but I 

# prefer to make the connections explicitly 
connect hosta 

connect hostb 
use table 

# remove all old logs in current directory 
!rm *.l 

# compile the script 
!scc script 

# change directory to the test directory on hosta and hostb 
red hosta /usr/testing/testl 

red hostb /user/testusr/testl 

# remove all old logs in the test directories on hosta and hostb 
remd hosta rm *.l 

remd hostb rm * . 1 

# copy the script binary to hosta and hostb 
put hosta script 

put hostb script 

(continued on following page , . .) 
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# eminstall the binaries 

# eminstall needs to know the value of the EMPOWER variable on the 

# run -time machines 

rcmd hosta EMPOWER=/usr/ empower $EMPOWER/ Ins tall /eminstall script 
rcmd hostb EMPOWER=/usr/ empower $EMPOWER/ Install/ eminstall script 

# start the test 
start all 

# wait for the scripts to finish 
wait 

# get the log files from scripts back to the master Mix 
get hosta * . 1 

get hostb *.l 

# extract the timestamps from the log files 
! extract * . 1 

# report from the extract files 
! report 

# done 
quit 
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3.0 Extract 

The Extract and Report tools provide response time information required for 
evaluating the abilities of your system under test (SUT). During script execution, 
time stamps are placed at the beginning and end of various elements of the log 
files. 

Extract scans for these time stamps to identify the beginning and ending of 
transactions, functions, and scenarios. Then, Extract retrieves these time stamps 
saving them in ASCII files called the transaction file, the function file, and the 
scenario file. 

Using these ASCII files, Report calculates response times and produces statistical 
reports. You also can use your own statistical software package to evaluate the time 
stamp data retrieved by Extract. 



3.1 Response Time 

Response time is defined by US government regulations, document (GSA) FPR 1- 
4.11, as the time that elapses between the transmission of the last character of a 
command and the receipt of the first printable character of the SUT's response. 
Transmission of a command typically is completed with activity on the keyboard (or 
mouse, for an X terminal or PC). A response from the SUT is generally in the form 
of displayed text or an updated image on your terminal. 

On many systems and with many applications, the first printable character of a 
response often denotes that a transaction is in progress. Messages such as 
"busy. .." or "working. . appear when transactions on the SUT begin. In such 
cases, defining the end of the response time as the time at which the first character 
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is received from the SUT may not be desirable. By using this definition, you would 
determine the time required by the SUT to generate the "busy. . message, not 
the time required by the SUT to complete the work associated with a transaction. 
With the EMPOWER products, you can mark activities to define the beginning and 
ending of transactions in a script. Therefore, you can specify response time as the 
time that elapses between an activity's initiation (by the user) and the completion of 
some or all work associated with the activity (by the SUT). 



3.2 Defining Transactions 

You have a great deal of flexibility for defining the beginning and ending of certain 
activities. In each script file, you should mark locations that make response times 
generated during a multi-user test correct and meaningful. 

Response times can be calculated for three categories of activity: transactions, 
functions, and scenarios. Functions and scenarios are defined in the script by the 
following functions: Beginf unction ( ) , Endf unction { ) , Beginscenario ( ) , and 
EndscenarioO . Transactions are defined in EMPOWER and EMPOWER/X 
scripts by the Namet ransac t ion { ) , Begintransac t ion ( ) f and 
Endtransaction{ ) functions, and in EMPOWER/CS by the Begintimer { ) and 

EndtimerO functions. 

Transactions represent individual types of user activities. For example, you may 
choose to define one or more script interactions as transaction type "login." Script 
execution will generate a response time for each interaction separately, classifying 
them as "login" transactions. Report will indicate the average response time for all 
"login" type transactions. 

In EMPOWER/CS scripts, transactions are defined by the Begintimer ( ) and 
End timer ( ) functions. The word "timer" is used for these functions instead of 
"transaction" to avoid confusion between true database transactions and the user- 
level time stamps recorded in a script In most cases, the term "timer" may be 
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substituted for "transaction" within this documentation. Also, the EMPOWER/CS 
Monitor and EMPOWER/CS reports will refer to time stamps generated by the 
Begintimer ( ) and Endtimer ( ) functions as "transactions." 

Functions contain a set of script interactions. The difference between functions 
and transactions is how the interactions are time-stamped. While individual 
interactions in a transaction receive time stamps, an entire function receives only 
one pair of time stamps. Report will indicate the response time for completing all 
interactions that make up the function. This report will include any think time or 
type delays that occurred during the set of script interactions. 

Scenarios operate essentially the same as functions. Response time associated with 
a scenario is recorded for the entire set of interactions; however, scenarios 
typically are used to define an entire user session. For example, during script 
development, you may define a "word processing" scenario which contains fifteen 
minutes of activity related to word processing. Generally, a scenario represents an 
entire script. 



3.3 Time Stamp Categories 

Time stamps represent the starting and ending times of transactions, functions, and 
scenarios. Each executing script creates a log file that includes time stamps for each 
transaction. Additionally, a time stamp is written to a log file every time one of the 
following functions is encountered in a script: Beginf unction { ) , Endf unction ( ) , 
Beginscenario{ ) , or Endscenario { ) 

Used only to name transactions in EMPOWER scripts, the Name transaction ) , 
Begintransaction( ), and Endtransaction ( ) functions do not cause time 
stamps to be written to the log file. EMPOWER automatically recognizes each 
transaction (Le., Xmit-Rcv pair) and records one of four types of time stamps in the 
log file as described below. 
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The two time stamps associated with transmitting a message from the emulated 
user are called XT1 and XT2. Usually, keyboard input is considered a transaction. 
XT1 is the time at which the first character is sent to the SUT; XT2 is the time at 
which the last character is sent to the SUT. The difference between XT1 and XT2 is 
the time required to type a command (Note: This time is affected by type rate 
delay). 

The time stamps associated with receiving messages from the SUT are called RT1 
and RTZ RT1 is the time at which the first character of the response is received 
RT2 is the time at which the last character of the response is received. The 
difference between RT1 and RT2 is the time the SUT requires to send an entire 
message. The default response time for each transaction is defined as the 
difference between XT2 and RT2. 

For EMPOWER/X, the XT1, RT1, XT2, and RT2 time stamps are recorded only if 
you insert Begintransaction( ) and Endtransaction{ ) functions in the script 
These functions must be placed carefully around KeyString { ) functions and their 
corresponding Textrcv ( ) functions. 

For EMPOWER/CS, time stamps are recorded in the log file for the 
Begintimer (), End timer (),Beginfunction(), Endf unction ( ) , 
BeginscenarioO, and Endscenario ( ) functions. Transactions are defined in 
EMPOWER/CS scripts by the Begintimer { ) and EndtimerO functions. The 
word "timer" is used instead of "transaction" in these functions to avoid 
confusion between true database transactions and the user-level time stamps 
recorded in a script The difference between EMPOWER/CS "timers" and 
EMPOWER "transactions" is that timers have a begin and end time recorded, 
while EMPOWER transactions have Xmit/Rcv time stamp pairs associated with 
them (as described in the preceding paragraphs). 

Response time for functions and scenarios is calculated as the difference between 
each time stamp for the Begin and End functions. For example, if a 
BeginfunctionO function executes at 21:28:25.52 and the corresponding 
EndfunctionO function executes at 21:2825.76, then the response time for this 
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function is 024 seconds. If a function contains Think ( ) functions, response time 
will include the time the emulated user spends "thinking." Beginfunction( ) and 
Endf unction ( ) functions should be inserted to define specific user activities that 
will make resulting response time reports meaningful. 



3.4 Accounting for Midnight 

If you execute an emulation that starts before and ends after midnight, time stamps 
will be placed in the log files that reflect the actual time of day. However, Extract 
ensures that these time stamp values do not cause erroneous response time 
reports. 

When Extract scans each log file, it looks for the passing of midnight If the passing 
of midnight is detected, Extract will add 24 to the hour value of each subsequent 
time stamp. 

For Report to generate correct throughput results for a multi-user emulation that ran 
past midnight, Extract must detect midnight in every log file. Therefore, each log 
file must contain an entry from the first day of the emulation. 



3.5 Extract Syntax 

The syntax of the extract command is shown in the following extract usage 
message. You can access this screen by entering the extract command with the 
parameter 
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$ extract - 

EMPOWER V3 . 1 . 8 , Serial#ROOOOO-000 , Copyright PERFORMIX , Inc. 1988-95 
Usage : 

extract [-xrsd] [-f filename] [-i scriptlist | script ...] 



Options : 



-x 
-r 
-s 
-d 
-f 
-i 



filename 
scriptlist 



Causes XT1 timestamps to be extracted 
Causes RT1 timestamps to be extracted 
Subtracts timeout times from event times 
Discards events containing timeouts 
Names the timestamp files filename. [SFT] 

Reads script names from scriptlist file (- is std input) 



Notes 



EXTRACT creates three timestamp files. 
XT 2 and RT2 timestamps are extracted by default. 
Data extracted from one log file is stored in script . [SFT] . 
Data extracted from multiple log files is stored in extract. [SFT] . 
EXTRACT prints the number of remaining log files as they are extracted. 
Script names read from scriptlist file must be newline delimited. 
Examples : 

extract scriptl 

extract scriptl script2 script3 
extract -f 3user scriptl script2 script3 
extract -r * . 1 
extract -i scriptlist 



3.5,1 Selecting Time Stamps to Extract 

As described in Section 3.3, four types of time stamps are produced for 
EMPOWER and EMPOWER/X scripts that mark transaction response time: XT1, 
XT2, RT1, and RTZ By default, Extract extracts the time stamps XT2 and RT2 from 
the log file. Response time generally is considered to be the difference between 
XT2 and RT2, since this amount represents the time required for the system to 
respond completely to an input but does not include the time required for the user 
to make the input 

You can use the -x and -r options of the extract command to specify that the 
time stamps XT1 and RT1 are extracted, respectively. Using one or both of these 
options, you can override the defaults and will define your own response times. 
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For example, to extract XT2 and RT1 time stamps (which complies with GSA 
specifications), you would type the following command: 

$ extract -r *.l 

Mote that if you specify the -x option, the XT1 time stamps are extracted but the 
XT2 time stamps are not. Likewise, if you specify the -r option, the RT1 time 
stamps are extracted but the RT2 time stamps are not. Under no circumstances are 
both the XT1 and XT2, or RT1 and RT2 time stamps extracted in a single execution 
of Extract 



3.5.2 Options to Handle Timeouts 

Two options of the extract command control extraction of time stamps from a log 
file that contains timeouts. The -s option calculates response time for a function 
containing a timeout by subtracting the timeout time from the extracted function 
times. The -d option discards functions containing timeouts; Le, the response time 
for an event containing a timeout is not calculated (Note: These options apply only 
to scripts using BeginfunctionO and Endf unction ( ) functions.) The -d option 
generally is preferred for log files that contain timeouts. 

The extract command is executed in the following examples to demonstrate the 
-s and -d options: 



[diane@joelle] extract example2.1 

EMPOWER V3 . 1 . 8 , Serial#R00000-000 , Copyright PERFORMIX, Inc. 1988-95 
1 

warning: can't open example2 . 1 . 1 
[diane@joelle] extract example2.1 

EMPOWER V3 .1.8, Serial#R00000-000 , Copyright PERFORMIX, Inc. 1988-95 
1 

[diane@joelle] cat example2.F 

15:35:33.43 15:36:05.68 " shell_commands " 
[diane@joelle] extract -d exaraple2 
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l 

[diane@joelle] cat examplo2.P 
15:35:33. 43 zz : zz : zz . zz " shell_commands " 
[diane@joelle] extract -s example2.1 

EMPOWER V3 . 1 . 8 , Serial#ROOOOO-000 , Copyright PERFORMIX, Inc. 1988-95 



The following EMPOWER log file was created by the script used in the above 
examples that executes shell commands: 





»> 


Port : telnet : localhost 




»> 


Log : example2 . 1 




»> 


Date: Thu Oct 13 15:35:24 1994 




»> 


Command: example2 -d telnet : localhost 




EMPOWER V3.1.8, Serial#ROOOOO-000 , Copyright PERFORMIX, Inc. 1988-95 




»> 


Beginsource ( " example2 " ) 




»> 


22 Set (CDELAY) 




>» 


23 Typerate(5.00) 




>>> 


25 Thinkuniform{1.000,2.500) 




»> 


26 Seed{7072) 




>>> 


27 Timeout (30/ CONTINUE ) 




»> 


28 Unset (NOTIFY) 




»> 


29 Signal (USER-DEF) 




»> 


32 Term (ZOOM, VT100 | LINES24 | AUTOWRAP) 




»> 


34 Rcv(" : ") 




»> 


RT1 15:35:24.62 




SunOS 


UNIX (joelle) 




login 






»> 


RT2 15:35:24.63 




»> 


Think 1.499 




»> 


XT1 15:35:25.65 




>» 


36 Xmi t (" empower A M") 




»> 


XT 2 15:35:27.25 




»> 


37 Rcv(" : ") 




»> 


RT1 15:35:27.73 






( continued on following page . . .) 
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empower 
Password : 

»> RT2 15:35:27.83 

»> Think 2.333 

»> XT1 15:35:29.84 

>» 39 Xmit("WickleOne A M n ) 

»> XT2 15:35:31.89 

»> 40 Rcv("] " ) 

»> RT1 15:35:32.03 

Last login: Thu Oct 13 15:34:45 from LOCALHOST . per for 

SunOS Release 4.1.2 (GENERIC) #2: Wed Oct 23 10:52:58 PDT 1991 



MODEM USERS: 



attl:tty22 dialout at up to 2400. 
attl:tty24 dialout at up to 9600. 
joellerttya dialin at up to 9600 (703-760-9241). 



120MB tape 
3 1/2 floppy 



/dev/rmtO 
/dev/fdO 



(fdformat to floppy) 



run openwin if you want OpenWindows 
inc : no mail to incorporate 
[ empower© j oelle ] 



RT2 15:35:33.43 
44 Beginscenario ( " example2 " ) 15:35:33.43 
46 Beginf unction ( n shell_commands" ) 15:35:33.43 
Think 1.893 
XT1 15:35:34.44 

51 Xmit( M date A M" ) 
XT2 15:35:35.47 

52 Rcv{"% ") 
RT1 15:35:35.53 



>>> 
>>> 
»> 
»> 
»> 
>» 
>» 
>» 
>» 
date 

Thu Oct 13 15:35:35 EDT 1994 
[ empower @j oelle] 
»> Timeout 15:36:05.67 

»> 57 Endf unction ( " shell_commands " ) 15:36:05.68 
»> Think 1.220 



»> XT1 15:36:06.70 

»> 58 Xmit ("exit A M" ) 
»> XT 2 15:36:07.76 

( continued on following page . . . ) 
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>>> 



>>> 



59 Wait (2) 

RT1 15:36:07.78 



exit 



>>> 



RT2 15:36:07.78 



>» 



>>> 



>» 



61 Endscenario { " example2 " ) 15:36:07.92 
Endsource { ) 
Closed: telnet port 



3.5.3 Redirecting Extract Output 



When Extract reads a script log file for time stamp data, it places the data in, if 
appropriate, a transaction file ending with "T", a function file ending with "F", and a 
scenario file ending with ".S". If Extract reads only one log file, the prefix of these 
files will be the same prefix of the file that Extract read 



Example: 

$ extract examplel 

The above example would create files called examplel. t, examplel. s, and 
examplel .f. When Extract scans more than one log file for time stamp data, it 
places the time stamp data in files called extract ,T f extract . s, and extract . f. 

In either case, if you want Extract to place the time stamp data in files with a 
different prefix, you can do so with the -f option of the extract command The 
parameter of the - f option is the prefix name of the time stamp data files. The 
following command will place Extract output in files called luser . T, luser . s, and 
luser . F: 

$ extract -f luser examplel 
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3.5.4 Log File Specification 

Each user in a multi-user emulation creates a separate log file. When you execute 
Extract, you must specify the log files to be extracted in one of two ways. 

One method for specifying log files is with the -i option. With this option, you 
specify either a file name or a hyphen as a parameter. The file name specifies a file 
containing a list of all log files to be extracted The hyphen specifies that Extract will 
receive the list of log files from standard input— typically this means that you enter 
the log file names at the UNIX script driver machine. 

For example, if the file loglist contains a list of log files to be extracted, the 
following extract command will use that list 

$ extract -i loglist 

If you wish to enter the log file names at the UNIX script driver, use the following 
extract command: 

$ extract -i - 

The most common method for specifying log files is to specify file names directly 
in the extract command The extract command's script parameter is the name, 
or prefix, of the log file that Extract will scan for time stamp data. Extract adds a .1 
extension to the name specified If you gave your log file a name other than the 
one given by default during script execution, make sure that you specify the 
correct log file name. You may specify multiple log files in one extract 
command— simply list all log file names as parameters. 

Examples: 

$ extract examplel example2 example 3 

$ extract examplel .1 example2.1 example3.1 
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You also may use the wild card character * to specify multiple files. 

$ extract example*. 1 
$ extract user*.l 
$ extract * . 1 

Note that Extract will recognize the J extension and will not try to add an additional 
extension. In the last example (extract * . 1, often used in multi-user load tests), 
Extract will use all files in the current directory that have the .1 extension. 

When Extract scans multiple files, it will display a number on the UNIX script driver 
that indicates the remaining number of log files to be scanned This display is 
helpful when you have used the command extract * . 1 to scan all files with the .1 
extension. If you are running a ten user test, you should see the number "10" 
appear on the UNIX script driver when Extract executes. As each file is read, new 
numbers appear, counting down until all files have been read The following 
example demonstrates this process after all files have been scanned by Extract 



$ extract * . 1 

Extract: EMPOWER V3 . 1 . 8 , Serial#R00000-000 , Copyright PERFORMIX, Inc. 
1988-95 

10 987654321 
S 

5f Note: If you execute Extract for a ten user test and the first number displayed is 

~^ "11 " you probably need to delete an old log file. 
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3.6 Sample Extract Execution 

In the following example, Extract scans the log file called examplel . 1: 



$ extract examplel 

Extract: EMPOWER V3.1.8, Serial#ROOOOO-000 , Copyright PERFORMIX, Inc. 

1988—95 

1 
$ 



The number of log files to be scanned appears below the Extract Copyright 
statement In this example the number is 1. Extract places time stamp data in the 
files examplel. T, examplel . F, and examplel. S. The format of a time stamp is 
hh:mm: ss .xx where hh is the hour, mm is the minute, ss is the second, and xx is 
the hundredth of a second 

Assuming that we had added the appropriate Nametransac t ion ( ) or 
Begintransaction( ) and Endtransaction ( ) functions in the script, the file 
examplel .t might look like this: 

10:56:53.20 10:56:53.48 "date" 
10:56:56.40 10:56:52.01 "Is" 

If not, it would look like this: 

10:56:53.20 10:56:53.48 " " 
10:56:56.40 10:56:52.01 " " 



If we had specified the appropriate Beginf unction { ) or Endf unction { ) 
functions, examplel. f might contain the following records: 



10: 


56 


■02.11 


10:56:20.56 


" query_database " 


10: 


56 


.20.56 


10:56:22.66 


" enter_data n 


10: 


56 


30.70 


10:56:50.08 


"vi_session " 


10: 


56 


52.21 


10:57:02.23 


" qui t_dat abase " 
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If we hadn't specified Beginf unction ( ) or Endf unction { ) functions, the file 
would be empty. 

Because we extracted from only one log file, examplel . s would contain only two 
records: the number of log files scanned and time stamps for the beginning and 
end of the scenario. If we had extracted more logs, each log would have a 
beginning and end scenario time. 

1 

10:55:54.83 10:57:02.40 "examplel" 
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4.0 Report 

The Report tool reads Extracts output to generate response time and throughput 
data. This information can be presented in standard transaction, function, and 
scenario reports or in a Government Services Administration (GSA) compliant 
report. These reports are stored in two files: one with a . std extension, and one 
with a .gsa extension. The standard report is produced by default; the GSA report 
is generated with the -g option of the report command. 



4.1 Report Syntax 



The following usage message lists the syntax of the report command. You can 
access this menu by typing the report command with a hyphen: 



$ report - 




EMPOWER 


V3 . 1 . 8 , 


Serial#R00000-000, Copyright PERFORMIX, Inc. 1988-95 


Usage : 


report 


[-BEFSThmdcl2345678] [-b t] [-e t] [-f f] [-p n] 




[-u n] 


[-w n] t-s n] [script] 


Options 








-b t 


Changes begin time of sample to t 




-e t 


Changes end time of sample to t 

Default includes events ending in sample 




-B 


Includes only events starting in sample 




-BE 


Includes only events starting and ending in sample 




-F 


Causes a function report to be produced 




-G 


Causes a GSA report to be produced 




-S 


Causes a scenario report to be produced 




-T 


Causes a transaction report to be produced 




-h 


Suppresses headings 




-m 


Changes report units to minutes (default is seconds) 




-d 


Forces within values to be discrete, not cumulative 




-c 


Supresses default columns 




-[1-8] 


Forces default column n to appear 




-f f 


Changes the output file names to f.GSA and f.STD 




-p n 


Computes the nth response time percentile 




-u n 


Changes the number of users to n 




-w n 


Computes number of events completed within n units 




-s n 


Changes the size of . STD name fields to n (default: 14) 
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4,1.1 Specifying a Begin and End Time 

Report will calculate the duration of each emulated user's session which is used to 
calculate the system under test's (SUTs) throughput The duration is the difference 
between the begin time and the end time for each report. 

By default, the begin time is when the first Beginscenario { ) executes and the 
end time is when the last Endscenario { ) executes. However, Report will calculate 
statistics for all interactions in the Extract output file, including interactions that 
occurred before the first Beginscenariot) execution or after the last 
Endscenario ( ) execution. Therefore, if the default begin and end times are used, 
activities that occur before the first Beginscenario { ) execution or after the last 
Endscenario ( ) execution will cause erroneous results. 

To create reports that calculate data for a specified time other than the default begin 
and end times, use the -b and -e options of the report command The -b option 
specifies the report start time; the -e option specifies the report end time. The 
time is specified as hours (hh), hours and minutes (hh:mm), or hours, minutes, and 
Seconds (hh : mm : s s). 

You also may use the key words first and last with the -b and -e options. The 
option -b first specifies that the begin time is the time of the first 
Beginscenario { ) execution. The option -b last specifies that the begin time is 
the time of the last Beginscenario ( ) execution. 

The option -e first specifies that the end time is the time of the first 
Endscenario ( ) execution. The option -e last specifies that the end time is the 
time of the last Endscenario ( ) execution. The following examples demonstrate 
the -b and -e commands: 

$ report -b 10:20 examplel 

$ report -b 10:20 -e 11:20 examplel 

$ report -e last examplel 
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4.1.2 Specifying Events for a Time Range 

By default, report will include only the interactions that end in the specified time 
sample which ensures that an interaction is counted only once if it spanned two 
specified time samples. If you want to override the default and include the 
interactions that began within a specified range, use the -B option in the report 
command Specify the -be option if you want to include interactions that began and 
ended within a specified range. 

The following example report commands use the -b, -e, -b, and -e options. 
These examples will include interactions that began and ended between 10:20 and 
11:20: 

$ report -b 10:20 -e 11:20 -BE example 1 
$ report -beBE 10:20 11:20 examplel 

This last example includes interactions that began between 10:20 and 12:20: 

$ report -TppwbeB 80 90 2.5 10:20 12:20 examplel 



4.1.3 Report Selection 

The -s, -f, and -T options specify how the standard report will be generated The 
-s option will include a scenario report, the -F option will include a function report, 
and the -T option will include a transaction report You can select one, two, or all 
three of the options. If none of these options are selected, all three reports will be 
generated by default. If the script does not include BeginfunctionO and 
EndfunctionO functions in the script, producing a function report will not be 
possible. 
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4.1.4 Generating a GSA Compliant Report 

By default, Report generates a standard ( . std) report. If you need to generate the 
GSA compliant report, use the -g option of the report command: 

$ report -G 



4.1.5 Suppressing Report Headers 

By default, the STD report file will contain header information identifying column 
titles. If you do not want the header information included (perhaps to process report 
data with other UNIX commands) specify the -h option with the report command. 



4.1.6 Unit Selection 

By default, response times are reported in seconds. If your response times are 
very large, which may be the case with response times of compilations or data base 
sorts, then you may wish to change the unit of response time reporting to minutes. 
The -m option of the report command will cause Report to display response times 
in minutes. 



4.1.7 Within Value Selection 

Report has the ability to identify the number of events that completed within a 
specified amount of time. For example, you may want to know how many 
transactions completed within two seconds or less. 

To select a "within" value, use the -w option with a floating point number 
identifying the time. You can string a set of -w options together and list all of the 
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times. In the following examples, Report will generate a transaction report (-t) 
identifying the number of transactions that completed within (-w) 1 second, 25 
seconds, and 5 seconds. 

$ report -T -w 1 -w 2.5 -w 5 examplel 
$ report -Twww 1 2.5 5 examplel 

The -w option specifies a cumulative report meaning that for each "within" value 
specified, the report shows thetotal number of events completed within the 
specified amount of time. The -d option of the report command reports discreet 
"within" values. When multiple "within" values are specified, Report indicates the 
incremental number of events completed within the specified amount of time. 

For the above example, suppose: 

O five events were completed within one second, 

O three more events completed between one and two and a half seconds, and 
O seven more events completed between two and a half and five seconds. 

If the -w option is used to generate the report, the report will indicate that for the 
report at 

O one second, five events had completed 

O two and a half seconds, eight events had completed 

O five seconds, fifteen events had completed 

If the -d option also is used to generate the report, the report will indicate that for 
the report at 

O one second, five events had completed 

O two and a half seconds, three events had completed 

O five seconds, seven events had completed 
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4.1.8 Suppressing and Forcing Report Columns 

Report generates a standard report which includes a set of nine reporting columns. 
These columns are: Interaction Name (i.e., Scenario, Function, or Transaction), 
Total, Finish, Thruput, Median, Average, Minimum, Maximum, and Std-Dev. With 
the -c and -[1-8] options of the report command, you can generate a 
customized reporting format with some or all of these columns. 

The -c option suppresses the eight statistical columns; the Interaction Name 
column can not be suppressed. The - [1-8] options specify columns to be 
displayed by number. For example, suppose you want to generate a customized 
version of the standard report in which you show only the Interaction Name, Total, 
Finish, Average, Min, Max, and Std-Dev columns. In addition, you want to show the 
75th and 95th percentiles. In the report command, you would first suppress all 
columns with the -c option, then specify individual columns for display. The -p 
option specifies percentiles and the - f option specifies the name of the report file: 

$ report -c -125678 -pp 75 95 -f custom 
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This command creates the following report, custom, std: 



EMPOWER Standard Report 






Date: 


Wed Apr 


7 10:52:55 1993 






btart time: 


10:41:32 








Stop time: 


10:42:26 








Duration : 


00:00:54 








Mix: 


4 users 








Unit: 


seconds 








Scenario 


Total Finish Average Minimum Maximum Std-Dev 


P75 


P95 


scriptl 


4 


4 48.91 43.79 53.97 4.15 


51.86 


53.97 


Function 


Total Finish Average Minimum Maximum Std-Dev 


P75 


P95 


word_proc 


4 


4 3.16 2.62 3.80 0.42 


3 .19 


3 . 80 


db_query 


4 


4 3.54 2.34 5.71 1.30 


3.38 


5.71 


Overall 


8 


8 3.36 2.34 5.71 0.99 


3.38 


5 .71 


Transaction 


Total 


Finish Average Minimum Maximum Std-Dev 


P75 


P95 


date 


20 


20 0.24 0.10 0.45 0.09 


0.28 


0.35 


loginid 


4 


4 0.18 0.12 0.33 0.08 


0.16 


0.33 


logout 


4 


4 0.02 0.01 0.02 0.00 


0.02 


0.02 


Is 


20 


20 0.28 0.11 0.68 0.13 


0.32 


0.45 


passwd 


4 


4 5.00 2.58 6.95 1.61 


5.80 


6.95 


pwd 


4 


4 0.05 0.02 0.13 0.05 


0.02 


0.13 


term type 


4 


4 2.42 1.90 3.72 0.76 


2.12 


3.72 


who 


20 


20 0.26 0.10 0.55 0.11 


0.33 


0.43 


Overall 


80 


80 0.58 0.01 6.95 1.20 


0.33 


2.58 





4.1.9 Redirecting Report Output 

By default, Report places output in a file ending with the suffix, . std. The prefix is 
obtained from the Extract output files used to generate reports. 
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If you want Report to place output in a file with a different prefix, you can use the 
-f option of the report command 

The following command will place output in luser . std: 
$ report -£ luser examplel 



4.1.10 Percentile Selection 

Response times can be reported by breaking measured transactions into response 
p time percentiles. The -p option of the report command specifies that response 

yQ time percentiles should be calculated and reported. You should enter an integer 

~2 value between one and 100 after the -p option. As shown in the following 

■tI examples, you may set a series of response time percentiles in several ways. 

"is 

These examples specify that a transaction report will generate with the 70th, 80th, 

J3 90th, 95th, and 99th percentile response times. Remember that the -c option is 

^ used to suppress the standard report columns. 

f % $ report -c -T -p 70 -p 80 -p 90 -p 95 -p 99 examplel 

fp $ report -c -T -ppppp 70 80 90 95 99 examplel 

rl $ report - c - Tppppp 70 80 90 95 99 examp lei 
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The example report, examplel . std follows: 



EMPOWER Standard Report 



Date: 


Mon Oct 17 


16:26 


59 1994 






Start time: 


16:23:44 










Stop time: 


16:25:37 










Duration: 


00:01:53 










Mix: 


10 users 










Unit: 


seconds 










Transaction 


P70 


P80 


P90 


P95 


P99 


date 


0.50 


0.69 


1.04 


1.14 


1.65 


login 


2.04 


2.45 


2.97 


3.22 


3.35 


logout 


0.02 


0.02 


0.04 


0.04 


0.04 


Is 


2.60 


2.68 


3.06 


3.21 


3.79 


ps 


5.78 


5.87 


6.56 


7.72 


8.72 


who 


1.57 


1.94 


2.46 


3.15 


3.75 


Overall 


2.53 


3.12 


4.84 


5.83 


7.72 



A percentile is defined as a value below which a certain percentage of the 
observations fall. In this report, 90 percent of all transactions occurred in 4.84 
seconds or less, and 90 percent of the date transactions occurred in 104 seconds 
or less. 

Mote: If the -p option is not used, response time percentiles will not be reported. 



4J.11 Specifying Number of Users 

By default, Report uses the number of log files as the number of users, which is 
accurate if each emulated user creates one log file. If the number of emulated users 
is not the same as the number of log files created, you can change the number of 
users with the -u option of the report command The following command will 
change the number of users to 3Z 

$ report -u 32 examplel 
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4.L12 Changing the Field Name Size 

The field size in a standard report specifying the transaction, function, or scenario 
is 14 characters wide by default. With the -s option, you can change the field size 
to a minimum of 11 characters and a maximum of 100 characters. For more column 
space, use the -s option to specify a smaller field size. 



4.1.13 Script File Specification 

The report command's script parameter identifies the script that produced the log 
from which time stamp data was extracted Report will add a . s extension to the file 
name when searching for the extracted scenario file, a . f extension when 
searching for the extracted function file, and a .t extension when searching for the 
extracted transaction file. 

If you do not specify a script, Report looks for the files extract . s, extract . F r 
and extract, t. Recall that Extract writes to extract . s, extract . f, and 
extract .t when it extracts from more than one log file. 



4.2 Report Environment Variables 

In addition to configuring reports with command line options, you can configure 
them with environment variables. Report understands three environment variables. 

The first environment variable is e_vendor. If e_vendor is defined, Report will use 
its value in the GSA and STD reports as the name of the vendor for whom the 
report is being prepared. In the example reports shown in the following sections, 
E_VENDOR IS defined as "Your Company Name". 
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The second and third environment variables are e_activity and e_project. If 
either of these variables are defined, their values also will be displayed below the 
title of the GSA and STD reports. e_activity and e_project typically are used to 
identify SUT configuration and user load on the UNIX driver machine associated 
with the report. 



4.3 Sample Report Execution 

GSA and Standard reports can be viewed with UNIX commands such as more, cat, 
and pg. Examples of these reports follow. 
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4.3.1 The GSA Report 



Contents of exampleWSA - Part 1 



EMPOWER Scenario 


Summary Report 


Project : 
Vendor : 
Date: 
Activity: 


10 User Test 

Your Company Name 

Tue Oct 18 14:31:47 1994 

Your SUT Configuration 


Summary for scenario: 


Overall 


Start time: 
Stop time: 
Duration: 

Number of scenarios attempted: 
Number of scenarios completed: 
Completion rate: 


16:23:44 

16:25:37 

00:01:53 

10 

10 

0 . 09 scenarios per second 


Median time: 
Average time: 
Minimum time: 
Maximum time : 
Standard deviation: 


92.75 seconds 

93.78 

85.68 

101.18 

4.14 


Summary for scenario: 


" examplel" 


Start time: 
Stop time: 
Duration: 

Number of scenarios attempted: 
Number of scenarios completed: 
Completion rate: 


16:23:44 

16:25:37 

00:01:53 

10 

10 

0.09 scenarios per second 


Median time: 
Average time: 
Minimum time: 
Maximum time : 
Standard deviation: 


92 .75 seconds 

93.78 

85.68 

101.18 

4.14 
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Contents of examplel.GSA - Part 2 

EMPOWER Interactive Response Time Summary Report 



Project : 
Vendor : 
Date: 
Activity: 

Summary for transaction: 

Start time: 
Stop time: 
Duration: 

Number of transactions attempted: 
Number of transactions completed: 
Completion rate: 

Median time: 
Average time: 
Minimum time: 
Maximum time: 
Standard deviation: 

Summary for transaction: 

Start time: 
Stop time: 
Duration: 

Number of transactions attempted: 
Number of transactions completed: 
Completion rate: 

Median time: 
Average time: 
Minimum time: 
Maximum time: 
Standard deviation: 

Summary for transaction: 

Start time: 
Stop time: 
Duration: 

Number of transactions attempted: 
Number of transactions completed: 
Completion rate : 

Median time: 
Average time: 
Minimum time: 
Maximum time: 
Standard deviation: 



10 User Test 

Your Company Name 

Tue Oct 18 14:31:47 1994 

Your SUT Configuration 

Overall 

16:23:44 

16:25:37 

00:01:53 

230 

230 

2.03 transactions per second 

1.29 seconds 

1.90 

0.00 

8.72 

1.89 

Unspecified 

16:23:44 

16:25:37 

00:01:53 

180 

180 

1.59 transactions per second 

1.58 seconds 

2.10 

0.00 

8.72 

2.03 

"who" 

16:23 :44 

16:25:37 

00:01:53 

50 

50 

0.44 transactions per second 

0.91 seconds 

1.18 

0.28 

3.75 

0.92 
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The GSA report is formatted to meet US Government GSA standards. Separate 
GSA reports are prepared for each type of interaction measured (transaction, 
function, and scenario) if the interaction has at least one occurrence in the report 
period For each type of interaction, the following reports may be generated: 

O Overall Summary— a summary of all occurrences of the interaction 
O Unspecified Summary— a summary of unnamed interactions 
O Named Interaction Summary— a summary of named interactions 

Note: Unspecified transactions are transmit-receive pairs that are not named with 

Nametransaction { ) or Begintransac t ion ( ) and Endtransac t ion { ) . 

Unspecified functions and scenarios would result only if the string in the 

Beginfunction( ) /Endf unction ( ) or Beginscenario ( ) /Endscenario { ) 
functions was null (e.g„ Begin funct ion ( ,,n ) ). However, you rarely would use 
these functions in such a way. 

Each GSA report includes a title, the report date, and start and stop times of the 
extracted data. 



43.1.1 Start Time and Stop Time 

The start time for each report is the earliest moment at which a Beginscenario ( ) 
function was executed. The stop time is the moment at which the last 
Endscenario () function completed. The duration is the difference between the 
start and stop times. The default start and stop times are overridden by the -b and 
-e report options as described in section 4.11. 



4.3.1.2 Events Attempted and Completed 

The GSA format also displays the number of events attempted and completed Any 
interaction that begins during script execution is an attempt, even if it did not end. 
For example, the execution of a Beginf unction { ) function without the execution 
of the corresponding Endf unct ion ( ) function is an incomplete attempt 
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4.3.1.3 Completion Rate 

The completion rate is computed as the number of completed events divided by 
the duration of the emulation. This completion rate identifiesihrou^/ipui of the 
SUT. 



43*1.4 Median 

The median is the middle value, or the arithmetic mean of two middle values, in a 
distribution. In this case, median refers to the response time value that half of the 
interaction response times are greater than and half are less than. 



4.3.1J5 Average 

The average is the arithmetic mean of a distribution. The average interaction 
response time is the sum of the response times divided by the number of 
interactions. 



4.3.1.6 Minimum 

The minimum is the smallest value in a distribution. In our reports, minimum refers 
to the minimum interaction response time value. 



4.3.1.7 Maximum 

The maximum is the largest value in a distribution. In our reports, maximum refers 
to the maximum interaction response time value. 
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43.1.8 Standard Deviation 

Standard deviation is a measure of dispersion in a distribution. It is defined as the 
square root of the arithmetic average of the squares of deviations from the mean. 
For our reports, standard deviation is used in conjuction with the average to help 
determine the amount that each interaction's response time varies from the 
average. 

Note: Using percentiles often is easier for obtaining information on interaction 
response time distribution. 

For more information on these statistical measurements, you can refer to any 
statistical reference text 



4.3.2 The Standard Report 

An example of a typical EMPOWER standard report follows: 
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Contents of examplelSTD 



EMPOWER Standard Report 






Project : 


10 User Test 




Vendor : 


Your 


Company Name 




Date: 


Tue Oct 18 16:29:48 


1994 


Activity: 


Your 


SUT Configuration 


Cf avt - +— A Tr\t~. . 

isLalt Lllue . 


16:23 


:44 






Stop time: 


16:25 


:37 






Duration : 


00:01 


:53 






Mix: 


10 users 






Unit: 


seconds 






Scenario 


Total 


Finish 


Thruput 


Median Average Minimum Maximum Std-Dev 


examplel 


10 


10 


0.09 


92.75 93.78 85.68 101.18 4.14 


Transaction 


Total 


Finish 


Thruput 


Median Average Minimum Maximum Std-Dev 


who 


50 


50 


0.44 


0.91 1.18 0.28 3.75 0.92 


Unspecified 


180 


180 


1.59 


1.58 2.10 0.00 8.72 2.03 


Overall 


230 


230 


2.03 


1.29 1.90 0.00 8.72 1.89 





The STD report contains the same information as the GSA report in a more 
condensed format This report displays summary information for each event 
(interaction) type. See Section 4.3.1 above. 

Like the GSA format, these summaries include information on specific events as 
well as overall and unspecified event summaries. The report columns identify the 
total number of attempted events; the number of completed events; the event's 
throughput; the event's median, average, minimum, and maximum response times; 
and the standard deviation of response times. (Note: The unspecified event 
category applies only to EMPOWER, not to EMPOWER/X or EMPOWER/CS) 
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5.0 Draw 

Using one or more standard Report files, the Draw tool creates bar charts that 
compare results of a multi-user test Draw can be used to compare statistics of 
several transaction types for a single user emulation or to compare several multi- 
user emulations. This tool will generate bar charts that contain up to 60 events 
found in a single standard report and also will compare a single transaction, 
scenario, or function for up to 60 different multi-user emulations. 

Draw provides an added dimension to Report results. The output of Report 
answers such questions about a single user emulation as: 

O "What was my average response time during the 16-user run?" 

O "How many data base updates can the system complete in an hour when 100 users 
are active?" 

The output of Draw answers questions about one or more multi-user emulations 
such as: 

O "How does my average response time change as the workload increases from 10 
users to 100 users?" 

O "How does the 80th response time percentile look for each function in the 16 user 
run?" 

Draw produces bar charts, or histograms, that can be viewed on-line or printed on 
any system printer. The output of Draw is in ASCII format and contains no printer- 
specific characters. 

The following figure shows a sample Draw output that identifies the change in 
response time as the number of users on a system is increased. After eight users, 
the system under test was saturated, forcing the response time for an additional 
user load to increase significantly. 
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Sample Draw Output—Response Time Vs. Number of Users 



EMPOWER Bar Chart 



Function : 

query 

7.5 + 



R 
e 
s 

P 
o 
n 
s 
e 

T 
i 
m 
e 

s 
e 
c 
o 
n 
d 
s 



6.0 +- - 



4.5 + 



3.0 +- - 



1.5 +- 
|@ 
|@ 

.0 +@- 

i 



@ 
@ 
& 
@ 

_<a- 
2 



Legend : 

@ - Average 



Number 



@ 

— @— 
8 

o f 



e 



@ 
@ 
@ 
@ 
@ 

-<a- 
1 
6 



users 



f + 



Number of users 



| Response Time seconds | 



+ + 



| Users | 


Input file | 


Average 


i i i 


luser.STD | 


1.14 


1 2 | 


2user.STD | 


1.19 


1 4 1 


4user . STD | 


1.55 


1 8 | 


8user . STD | 


2.61 


1 16 I 


16user.STD | 


6.13 
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5.1 Batch Mode Execution 



Draw can be executed in batch mode if a file exists that specifies the chart's format. 
The following example shows a bar chart's specification file that will compare 
minimum, maximum, and average response time of "query" and "update" 
transactions during a multi-user run. 



BEGIN 

TITLE = EMPOWER Bar Chart 

XTITLE = Transaction 

YTITLE = Response Time seconds 

INPUT = 16user.STD 

EVENT = Transaction 

X ~ query, update 

Y = Average, Minimum, Maximum 

LEGEND = @, | , * 

ORGANIZE = CLUSTERED 

YMIN =0.0 

YMAX = 20. 

COMMENT = Created for ABC Corp 
COMMENT = January 2, 1991 
END 



If this file is called draw, spec, then the following command will execute Draw in 
batch mode. (Note: The complete syntax for the draw command is discussed in 
Section 5.4), 



$ draw -s draw .spec -o draw* out 

Draw: EMPOWER V3 . 1 . 8 , Serial#R00000-000 , Copyright PERFORMIX, Inc. 1988-95 
Bar chart (s) drawn. 
Draw exited. 
$ 



As directed by the specification file, Draw would create a bar chart that places 
response time on the Y-axis and transaction types on the X-axis. Response times of 
the "update" transactions are noticeably larger than response times for the "query" 
transactions. 
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Sample Draw Output for Batch Mode Execution 











EMPOWER Bar 


Chart 








Start time 20:27: 


01 






Legend: 








Stop time 


20:32: 


42 






@ - 


Average 






Duration 


341.06 


seconds 




1 " 


Minimum 






Mix 


16 users 






* _ 


Maximum 






Input file 16user 


. STD 














20.0 +- 












* 




R 


1 












* 




e 


| 












* 




s 


1 












* 




P 














* 




o 


16.0 +- 
















n 


1 






* 






* 




s 


| 












* 




e 


| 












* 


















* 




T 


12.0 +- 






* 






* 




i 


■ 
1 






* 






* 




m 


| 












* 




e 


| 






* 






* 






• 
1 






* 






@ * 




g 


8.0 +- 






* 










e 








* 






@ * 




Q 








@ * 






@ * 




O 








<a * 






@ * 












@ * 






@ * 




d 


4.0 +- 






@ * - 






@ * 




s 








<a * 






@ * 












@ * 






@ * 












@ * 






@. * 












e|* 






©|* 






.0 +-- 






— 






@j* 
































A 




B 












T r a 


n s a c 


t i o n s 












































I 


Transaction 


1 




Response time seconds 


l 








































1 ID | 


Description 


1 


Average 


| Minimum 


j Maximum 


l 








































1 A | 


query 




1 


6.13 


| 0.89 


| 16.35 


I 




I B | 


update 




1 


8.87 


| 0.61 


| 19.98 


I 
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5.2 Interactive Mode Execution 

Specifications for bar charts generally are created interactively. To enter interactive 
mode, change to the working directory where your standard report files are stored 
and enter the draw command without any options. The working directory must 
contain some standard report files or Draw will display an error and terminate. 

The following example shows an interactive session that will produce the 
specification and chart shown in section 5.1. In this example, cr indicates pressing 
the carriage return key: 



$ draw 

Draw: EMPOWER V3 . 1 . 8 , Serial#ROOOOO-000 , Copyright PERFORMIX, Inc. 1988-95 

Please respond after each => prompt . 
Press RETURN to accept a default. 
Type quit at any time to exit. 

Please select one or more INPUT file names. 
Available files in the current directory are: 
1) 16user.STD 2) luser.STD 3) 2user.STD 

4) 4user.STD 5) 8user.STD 
Enter * to select all the files. 
=> 1 

Please select an EVENT to be charted. 

1) Scenario 2) Function 3) Transaction 

Default is 1) Scenario 
=> 3 

Please select one or more Transactions for the X axis . 
Available X axis values are: 

1) Overall 2) Unspecified 3) query 4) update 

Default is 1) Overall 
=> 3 4 

Please select one or more statistics for the Y axis . 
Available Y axis values are: 

1) Total 2) Finish 3) Thruput 4) Median 

5 ) Average 6 ) Minimum 7 ) Maximum 8 ) Std-Dev 
Default is 5) Average 

=> 5 6 7 

Please enter 3 LEGEND characters. 
Default characters are @ | * 
=> CR 

(continued on following page ...) 
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Please select an ORGANIZE value. 

1) CLUSTERED 2) HIDDEN 

Default is 1) CLUSTERED 
= > CR 

Please enter YMIN and YMAX values . 
Defaults are 0.0 and 20. 
= > CR 

Please enter the TITLE of the bar chart. 
Default is EMPOWER Bar Chart 
=> CR 

Please enter the X axis TITLE. 
Default is Transaction 
= > CR 

Please enter the Y axis TITLE. 
Default is Response Time seconds 
= > CR 

Please enter comments to be included in the bar chart. 
Type a blank line to end. 
-> Created for ABC Corp 
=> February 25, 1990 
=> CR 

Spec for bar chart is : 
BEGIN 

TITLE = EMPOWER Bar Chart 

XTITLE = Transaction 

YTITLE = Response Time seconds 

INPUT = 16user.STD 

EVENT = Transaction 

X = query, update 

Y = Average, Minimum, Maximum 

LEGEND = @, | , * 

ORGANIZE = CLUSTERED 

YMIN =0.0 

YMAX = 20. 

COMMENT = Created for ABC Corp 
COMMENT = February 25, 1990 
END 

Would you like to save this spec (y/n) ? 
Default is y) yes 
=> CR 

Please enter name of spec file. 
Default is draw. spec 
= > CR 

draw . spec exi s t s . 

Do you want to append or overwrite (a/o) ? 
Default is o) overwrite 
=> CR 

(continued on following page ...) 
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* 

Do you want to create another spec 


(y/n) ? 


Default is n) no 




=> CR 




Do you want to create the bar chart 


(y/n) ? 


Default is y) yes 




=> CR 




Please enter name of output file. 




Default is draw. out 




=> CR 




draw. out exists. 




Do you want to append or overwrite 


(a/o)? 


Default is o) overwrite 




= > CR 




1 bar chart written to draw. out 




Draw: normal completion. 





During this interactive session, a specification file called draw . spec was created 
and the bar chart created was stored in draw. out. These two files are identical to 
the files used in Section 5.1. 



5.3 Bar Chart Format 

Every bar chart created by Draw, interactively or in batch mode, is composed of 
four sections: header, figure, data table, and messages. If it contains 14 or fewer 
bars or clusters, the entire chart will fit on one standard 8-1/2 x 11 page . If there are 
more than 14 bars or clusters, the data table will continue to the next page. 



5.3.1 Header 

The header is the top portion of the chart. It consists of a centered title at the top, a 
legend on the right, and chart information on the left. The chart information 
displayed depends on the number of specified input files. If only one input file is 
specified, the start time, stop time, duration, number of users, and name of the 
input file will be displayed . If multiple input files are specified, the name of the 
transaction, scenario, or function that is charted will be displayed . 
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5.3.2 Figure 

The figure is displayed below the header. The range of the vertical axis is defined 
by the ymin and ymax values in the specification. Draw may fine tune your values 
to make the chart more visually appealing. The horizontal axis identifies each bar 
with an id depending on the number of input files specified If one input file is 
specified, the id will be a character related to the data table information. If multiple 
files are specified, the id will be the number of users in the corresponding input 
file. 

Each bar is composed of one to three legend characters depending on the y and 
organize fields in the specification. Every performance measurement specified in 
the Y field is associated with a specific legend character. 

If one performance measurement is specified for the y field, then the bars will be 
evenly spaced and will contain the same legend character. 

* 

* 
* 

* * 

* * * 

* * * 



If two or three performance measurements are specified for the y field and the 
organize value is clustered, each bar will contain its specific legend character 
and the bars will be grouped together in a cluster. 



fcjcample: 
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Example: 



@ * 
I @ * 



If two or three performance measurements are specified for the Y field and the 
organize value is hidden, each bar will contain two or three legend characters. 
The taller bars will appear hidden behind the shorter bars. 



Example: 

* 
* 

* * 
@ 

@ # 

# # 



Due to limited space, the chart occasionally is printed in hidden format even 
though the organize value is clustered. 

When the maximum value of a bar exceeds the value specified by ymax, a A 
character will be printed on the tip of the bar. Similarly, a v character will be printed 
on the horizontal axis at the bottom of the bar when the minimum value of a bar is 
less than the ymin value. 



The location of each bar or cluster depends on the number of specified input files. 
When only one file is specified, the bars or clusters will be distributed evenly on 
the horizontal axis. If multiple input files are specified, the bars or clusters will be 
arranged in increasing order according to the number of users identified in each 
input file. The distance between the bars or clusters will be proportional to the 
number of users that the bars or clusters represent, In cases where it is impossible 
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to place all the clusters proportionally, Draw will make adjustments and issue a 
warning message. 



5.33 Data Table 

The data table is located below the figure and lists the actual value of each bar 
drawn on the chart. When one input file is specified, an id will be assigned to 
each row of the table to correlate the contents of the table with the figure. When 
multiple input files are specified, each row will be identified by the number of 
users in each file. When there are more than 14 entries, the data table will print on a 
separate page. 



5.3.4 Messages 

Messages may appear below the table and include comments from the specification 
and any warning messages generated by Draw while processing the chart. 

When the data table prints on a second page, messages will appear below the figure 
with an additional message indicating that the data table is on a separate page. 
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5.4 Draw Syntax 



Now that we have an idea of the output that draw can create, let's look at the 
complete command syntax for Draw. The syntax is: 



$ draw - 






EMPOWER V3 . 1 . 


8, Serial#ROO000-O00, Copyright PERFORMIX, Inc. 1988- 


95 


Usage : 






draw 


[-q] [-s specfile] [-o outputfile] 




Options : 






-q 


Uses Quick Interactive Mode 




-s 


Uses batch mode with specfile as input specification file 


-o 


Assigns outputfile as the output file 




Notes : 






With 


no option specified, DRAW will enter the interactive 


mode . 


Interactive mode requires *.STD files in current 


working 


directory. 






The - 


-o option will be ignored in interactive mode. 




Without -o option, the default output file is draw. out. 




The - 


■q option can not be used together with the -s option. 




Examples : 






draw 






draw 


-q 




draw 


-s sample. spec 




draw 


-s sample. spec -o sample. out 





5.4.1 Default Interactive Mode 

Interactive mode is the most common way to operate Draw. To enter this mode, 
specify the command draw without any options. You will be able to create 
specifications and generate bar charts on-line. 

In interactive mode, Draw scans your current directory for a list of .STD files, then 
scans the files for performance measurements they contain. Draw uses this 
information to guide you through a series of questions that help Draw to produce a 
chart 
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Note: Since Draw scans only your current directory, you must run Draw in the 
directory where your standard report files are stored. 

When running Draw, you will be asked to select from a list of choices for each field. 
Since the list of choices is prepared from information in the standard report files, a 
default answer will be available for each question. You can accept a default value by 
pressing the return key at each prompt 

As the interaction continues, each of your choices are verified When all fields of a 
specification are obtained, the specification will be displayed on screen for 
verification. You can either save or discard the specification. 

When the first specification is created and saved, you will be asked to enter the 
specification file name. The default is "draw.spec". If you choose to create 
additional specifications, the process will be repeated. All specifications created in 
the same session will be stored in the same specification file. 

When you have completed all specifications, Draw will ask if your bar chart(s) 
should be generated. If you answer "no," Draw will exit from interactive mode, 
leaving you with just the specification file. If you answer "yes," you will be asked 
for the name of an output file; the default is "draw.out". Draw will generate a bar 
chart for each specification set in the specification file and exit 



5.4.2 Quick Interactive Mode 

You may discover that the default values for the option statements, comment, 

LEGEND, ORGANIZE, TITLE, XTITLE, YMIN, YMAX and YTITLE, are sufficient to 

execute Draw for your emulation. The -q option of the draw command specifies 
that these default values should be used. The resulting Draw execution can be 
completed more quickly than the normal interactive execution, since Draw will 
prompt you only for the required information. 
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Draw creates a specification file with the default name draw. spec. The output is 
placed in a file with the default name draw. out. 

The following example illustrates using the -q option: 



$ draw -q 

Draw: EMPOWER V3 . 1 . 8 , Serial #ROOOOO-000 , Copyright PERFORMIX, Inc. 1988-95 

Please respond after each => prompt. 
Press RETURN to accept a default. 
Type quit at any time to exit. 

Please select one or more INPUT file names. 
Available files in the current directory are: 
1) 16user.STD 2) luser.STD 3) 2user.STD 

4) 4user.STD 5) 8user.STD 
Enter * to select all the files . 
=> 1 

Please select an EVENT to be charted. 

1) Scenario 2) Function 3) Transaction 

Default is 1) Scenario 
=> 3 

Please select one or more Transactions for the X axis. 
Available X axis values are: 

1) Overall 2) Unspecified 3) query 4) update 
Default is 1) Overall 
=> 3 4 

Please select one or more statistics for the Y axis . 
Available Y axis values are: 

1) Total 2) Finish 3) Thruput 4) Median 

5) Average 6) Minimum 7) Maximum 8) Std-Dev 
Default is 5) Average 

=> 5 6 7 

1 bar chart written to draw. out 

Draw: normal completion. 

$ 
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5.43 Batch Mode with Specification File 

The -s option of the draw command is used to identify the specification file for 
bar charts to be produced The parameter of the -s option is the name of the 
specification file. 

Typically, specifications are created in interactive mode, then batch mode is run to 
create the chart. If you want to create the same chart for several emulations, you 
should answer questions in interactive mode, edit and duplicate the specification 
with a system editor, then run Draw in batch mode to create charts for all 
emulations. 

If multiple specifications are stored in your specification file, Draw will generate 
multiple bar charts separated by form feed characters. 



5.4,4 Batch Mode with Output File Mode 

The -o option identifies the output file for storing the generated bar charts. This 
option works only in batch mode (with the -s option) and is ignored in interactive 
mode. If no output file is specified, output is sent to the default file draw. out. 



53 Specification Syntax 

Specifications for bar charts may be created interactively by Draw (the most 
common method) or manually with any system editor. System editors often are 
used to copy and make minor changes to existing specifications. 

The first statement of each specification read by Draw is begin and the last 
statement is end. Multiple specifications may be stored in one file. Comments (not 
to be confused with the comment statement) must begin with a pound sign and 
may continue until the end of the line. Blank lines are allowed and are ignored 
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during processing. Each begin-end pair requires four statements that must appear 
on separate lines (see list below) and several optional statements. 

Except in the case of input files, Draw does not distinguish between upper and 
lower case letters. The names of input files in the input statement must be written 
exactly as they appear in your directory. 

The required statements are: 

O input - input files (the standard reports) 

O event - event to be charted (scenario, function, or transaction) 

Ox - list of scenarios, functions, or transactions 

O y - performance measurements (average, maximum, P90, ...) 

Each statement begins with a key word (statement name) and must be followed by 
a space and an equal sign: 

Incorrect 

Event= Transaction 
Event =Tr ans ac t i on 
Event Transaction 
evENT = tranSAction 

Note: If you operate Draw interactively, Draw will ensure that your specification 
has no mistakes. 



Correct 

Event = Transaction 
Event ^Transaction 
EVENT ^TRANSACTION 



5,5.1 INPUT 

input specifies the standard report files that Draw will read. When one file is 
identified, up to 60 X-axis values can be specified The Draw tool will generate a 
bar chart that compares different events in the same input file. 

If multiple input files are specified, only one X-axis value is allowed In this case, the 
bar chart compares an event across several emulations and up to 60 input files may 
be specified 
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Examples: 

INPUT = 16user.STD 

INPUT = mix25.STD, mixSO.STD 



5.5.2 EVENT 

event specifies the event to be charted The value of event can be Scenario, 
Function, or Transaction and only one value can be defined for each 
specification. 

Examples: 

EVENT = Scenario 
EVENT = Function 
EVENT = Transaction 



5.5.3 X 

x specifies a list of events that will appear on the X-axis of the bar chart. The names 
in the x value must appear in the first column of all input files under the selected 
heading in the event statement. If multiple files are specified in the input 
statement, the x value must contain only one item. If the input statement identifies 
only one file, up to 60 items can be specified . 

Examples: 

X = query, update 
X = Overall 



EMPOWER/CS Vl.0.1 



5-16 

Copyright PERFORMIX, Inc. © 1 995 



User's Guide— Multi-User Testing 



5.5.4 Y 

y specifies column headings of performance measures in the input files. The 
selected measures will be extracted from the input files and plotted along the 
Y-axis. Up to three headings can be specified. The names must appear in the 
column headings of all input files in the same specified form. 

Examples: 

Y = Thruput 

Y = Minimum, Average, Maximum 



5.5.5 TITLE 

title specifies the title of the bar chart. The default is empower Bar Chart. 
Example: 

TITLE = Minimum and Maximum Response Time 



5.5.6 XTITLE 

xtitle specifies the horizontal axis label. The default is the event value. 
Example: 

XTITLE = Number of Emulated Users 
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5,5.7 YTITLE 

ytitle specifies the vertical axis label. The default is determined by the y value as 
one of the following: 

O Response time unit as used in the input files. This value is chosen as the default 
when the specified Y value relates to response time (Median, Average, Std-Dev, P90, 
etc.). 

O Count is chosen as the default when the specified y value relates to count (Total, 
Finish, W30, W50, etc.). 

O Event/unit: where event is specified in the event statement and unit is the time 
unit used in the input files. This format is chosen as the default when the specified 
y value is throughput (Thruput). 

Example: 

YTITLE = Transactions /second 

5.5.8 YMIN 

ymin specifies the minimum value of the vertical axis. If this statement is not 
specified, Draw will assign a value so that all bars on the chart are not lower than the 
horizontal axis. The actual chart value may not be the same as the specified value. 
Draw may adjust your value to improve the chart's appearance. 

Example: 

YMIN = 0.000000 
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i 
i 

5.5,9 YMAX 

ymax specifies the maximum value of the vertical axis. If this statement is not 
specified, Draw will assign a value so that all bars on the chart are not taller than the 
vertical axis. The actual chart value may not be the same as the specified value 
—Draw may adjust your value to improve the chart's appearance. 

Example: 

YMAX =10000000 



5-5.10 LEGEND 

legend identifies each y value with a single character and each bar will contain the 
corresponding legend character. Performance measures have pre-defined default 
legend characters. 

Example: 

LEGEND = *, !, & 



5.5.11 ORGANIZE 

organize describes the format of bars to be drawn on the chart. The value of 
organize can be clustered or hidden. In the clustered format, all bars 
corresponding to the same event are grouped together with different legend 
characters for each bar. With the hidden format, all bars that correspond to the 
same event are combined into a single bar with different legend characters (the 
taller bars will hide behind the shorter bars). 
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Occasionally, due to limited space, two clusters in a clustered chart will collide with 
each other. In this case, Draw will force the output to print in the hidden format 
with a warning message. 

The default value of organize is clustered . 

Example: 

ORGANIZE = hidden 



5-5.12 COMMENT 

comment specifies a comment to be printed below the bar chart. It is the only 
statement that can be defined more than once in a specification. Comments are 
printed on the chart in the order they are written in the specification file. The 
maximum number of comment statements is 50. An example follows: 

COMMENT - This chart created by DL 
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6.0 Monitor 

The Monitor tool allows you to monitor script activity during script execution. This 
tool is useful during script development and multi-user load tests because it 
interprets and displays significant status information for executing scripts. 

Monitoring script activity during load testing is very difficult without Monitor 
because you must activate the display option for each executing script or browse 
through script logs to discover problems. The display option requires a terminal or 
workstation for each displayed script which would be extremely expensive, and 
browsing through log files is very time-consuming and inefficient 

Evaluating status information during a multi-user emulation is also very difficult 
without Monitor because you must rely on reports generated after the test. If 
resulting performance information is unsatisfactory, you would have to search 
through script log files to determine the cause of the problem. With Monitor, you 
can easily follow each script's activity and identify problems as they occur. 

Benefits of using Monitor are: 

O Simplified script debugging. Since you can monitor scripts as they execute, you can 
see how scripts have progressed. If a script becomes blocked, you immediately can 
detect the block, examine the log file of the script, or edit the source code. You do 
not have to exit Monitor to initiate edits. 

O You can perform real time presentations during a load test 

O You can monitor response time on line as the scripts run. 

O Script execution can be controlled dynamically. 
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6.1 Shared Memory 

When your scripts are compiled with the Sec, Xscc, or Cscc tools (which 
automatically include the Monitor library functions), they will continuously update 
current status information in an area of UNIX shared memory. Monitor then 
displays the information in a useful format More than one Monitor session can run 
simultaneously, and users can monitor their own scripts or all scripts running on the 
RTE machine. 

The maximum number of scripts allowed in shared memory depends on the 
maximum size of a shared memory segment configured in your UNIX kernel 
(shmmax), and on the number given as an argument in the command to start 
Monitor. (A description of this argument is given in section 63.11.) The default size 
for the number of shared memory segments is 1024, with 4096 being the 
maximum. 

Traditionally, script IDs are unique within a load testing session. Monitor enforces 
this uniqueness by allowing a script to "steal" the memory slot of another script 
having the same script ID. Therefore, if you run a test again after the first test 
completed, the second run will "re-use" the previous test's memory slot Users must 
be careful to designate different script IDs. If two scripts with the same script ID 
are executed concurrently, the second script will overwrite the first. 



6.2 The Curses Library 

Monitor is written using the UNIX curses library. Therefore, any terminal that can 
run other curses applications (such as "vi") can run Monitor. The number of scripts 
that can be displayed on one screen is determined by the number of lines 
specified in your terminal's curses definition or the value of your lines shell 
environment variable (if it is supported by your curses library implementation). To 
use Monitor, you must inform the system of your terminal type by setting your 
term variable (term for csh users). 
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For Bourne shell (sh) users, you can set your term variable by typing at the sh 
prompt: 

TERM=vtlOO; export TERM 

C-shell users would type at the csh prompt 

set term=vtl00 

or 

setenv term vtlOO 

Note: Of course, you would insert your appropriate terminal type in place of 
vtlOO. 

Some curses implementations do not gracefully fail if you do not specify a valid 
terminal type before executing a curses application. Some of them simply fail to 
execute the application and return you to the UNIX shell with no indication that a 
problem occurred. Others may create more serious problems, such as dumping 
core. If a core dump occurs, you should verify that your terminal type is in the 
system's terminf o data base for System V or /etc/termcap for BSD UNIX. User- 
friendly curses implementations normally will print a message like the following if 
they detect that your terminal type is unknown or invalid: 

< terminal type> : Unknown terminal type 

or 

I don ' t know enough about your <terminal type> terminal . 
If Monitor does not recognize your terminal, the following message will appear 
I don't know enough about your terminal to run mon! 
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6.3 Monitor Syntax 



This section describes usage information displayed from the UNIX shell. The usage 
menus for Monitor are displayed when you enter the command mon for 
EMPOWER, xmon for EMPOWER/X, or csmon for EMPOWER/CS, with a hyphen(- 
) as a parameter. The usage menus for each tool are identical. 



$ mon - 

EMPOWER V3.1.8, Serial#R00 000-000 , Copyright PERFORMIX, Inc. 1988-95 
Usage: 

mon [-.ekorwAS] [-v n] [-i n] [-s n] 

Options : 



-e 
-k 
-o 
-r 
-w 
-A 
-S 

-v n 
-i n 
-s n 



enter in dot mode 

do not display exited scripts 

kill processes attached to shared memory segment 
do not display scripts owned by others 
remove shared memory segment 
wrap log before edit 

use alternate character set (if available) 
print status of shared memory segment 
enter onto view n 
enter with interval n 

create shared memory segment for n scripts 



6.3.1 

The - . option starts Monitor automatically performing a ' . ' command. This 
command substitutes a single V character for control characters normally displayed 
as a two character ( A c) sequence. This option makes the screen easier to read and 
allows more data to be displayed when it contains many control characters. 
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6.3.2 -e 

The -e option specifies that exited scripts will not be shown in Monitor views 
during the session. The default mode displays all scripts. The -e option only 
displays executing scripts which allows you to focus on scripts that are still running 
without sorting through "dead" scripts or deleting scripts from shared memory. 



6.3.3 -k 

The -k option allows you to kill all currently running scripts. After entering this 
option, a verification statement will appear. You can kill only those scripts belonging 
to you. See the following example: 



$ mon -k 

This procedure kills processes owned by you that are attached to the 
EMPOWER shared memory segment. Continue? 



If you answer y to the prompt while scripts belonging to another user are running, 
the following message will be displayed 



The following processes can't be killed because you're not the 



owner . 




P1D 


Owner 


1674 


wendy 


1681 


wendy 


2053 


wendy 



If you want to force the kill of all scripts (even those not owned by you), you can log 
in as the super user and type "mon -k". 
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63.4 -o 

The -o option will start Monitor without displaying scripts that you do not own. 



63.5 -r 

The -r option allows you to remove the shared memory segment This option will 
not start Monitor. 

To remove the shared memory segment, you must own it (own either the first 
script to begin execution, or be the user who executes the mon, xmon, or csmon 
command, whichever occurs first), or be the super-user. If the shared memory 
segment is removed successfully, a message similar to the following will be 
displayed: 

Shared memory segment ID 0 removed. 
Shared memory semaphore ID 0 removed. 

If scripts are running, you must use the -k option to kill all scripts before the shared 
memory segment can be removed 

If you are not the owner and you try to remove the shared memory segment with 
the -r option, the following message will be displayed 

The EMPOWER shared memory segment must be removed by its creator 
<creatorname> . 

or 

The EMPOWER/X shared memory segment must be removed by its creator 
<creatorname> . 

You can force removal of the shared memory segment by logging in as the super- 
user and typing "mon -r" 
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If you are the owner of the shared memory segment, but scripts are still running 
and you try to remove the segment when scripts are still executing, the following 
message will be displayed: 

There are 10 processes attached to the EMPOWER shared memory 
segment . 

All EMPOWER script and Monitor processes must be killed before proceeding. 



6.3.6 -w 

The -w option causes log files to be wrapped before they are viewed. 



6.3.7 -A 

The -A option specifies that the alternate character set (line drawing characters) will 
be used if available on your system and for your terminal. Using the line drawing 
characters allows such features as a box drawn around the help windows. 

This function may not work on your terminal correctly (or at all) in the following 
three cases: 

O Although your terminal may have a line-drawing character set, your version of 
curses may not support it 

O Your terminal may have to be initialized into a mode that enables you to use the 
line-drawing character set For instance, the vtlOO requires that its alternate 
character set be assigned to the line-drawing character set by outputting the escape 
sequence <esc>)0 to the terminal. If you are not initialized into a line-drawing 
character set mode, you may see normal alphabetic characters in places where line- 
drawing characters should be, such as around the help screen. 

O The curses terminal definition for your terminal may not be correct 
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Because of the third reason listed above, specifications of -A are optional rather 
than the default. 



63-8 -S 



The -s option will print the status of the shared memory segment, as in the 
following example: 



$ mon -S 

EMPOWER V3 . 1 . 8 Serial#R00000-000 Copyright PERFORMIX, Inc. 1988-95 
Maximum number of sessions available in this shared memory segment 
Number of sessions currently attached to the shared memory segment 
Size of shared memory segment in bytes = <491440> 
Owner of shared memory segment = <ownername> 



The maximum number of sessions that can be monitored depends on your system. 
Normally, PERFORMIX sets the maximum at 4096 before the software is shipped 
and this amount cannot be changed 

The maximum number of sessions available is less than or equal to the maximum 
number of sessions that can be monitored. The default value is 1024. 

The number of sessions currently attached to the shared memory segment is the 
number of scripts and Monitor sessions currently running. 

The owner of the shared memory segment is the first user to execute the 
EMPOWER, EMPOWER/X, or EMPOWER/CS command that created the shared 
memory segment. This user will be either the first person to run a script or run 
Monitor. 
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6.3.9 -v 

Every time you start Monitor, you will enter View 1 by default. The -v n option 
allows you to enter a specified view. 

$ mon -v 3 



6.3.10 -i 

You can use the -i n option to start Monitor with the time interval n. Information 
O on the current screen will be updated every n seconds. The default interval value is 

five seconds, the maximum interval value is 3600 seconds, and the minimum value 
jt* is one. If you specify an interval value exceeding the maximum, the interval will be 

\| set to the maximum value. If you specify an interval value of zero, the interval will 

J5 be set to the default 

~ r '~ $ mon -i 2 

Ms 



6.3.11 -s 

The -s n option allows you to initialize the number of shared memory segments. 
The minimum value of n is four and the maximum value normally is set at 1024. 
This option is useful if you do not have enough shared memory available in your 
UNIX kernel or if you want to limit the number of scripts that can be monitored to 
display a sample of the running scripts. Scripts started when the shared memory 
segment is full will not be monitored 

Example: 

$ mon -s 64 
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Increasing the maximum number of sessions available in the shared memory 
segment is also useful if you are running an extremely large test. 

$ mon -s 2048 



6.4 Starting Monitor 

After a script is compiled, you use the mix command to begin multi-user testing. 
While the test is running, you can use Monitor to monitor script execution. Because 
Monitor is an interactive program, you can control script execution by entering 
various Monitor commands. 

The command to start Monitor for EMPOWER is mon; for EMPOWER/X, xmon; for 
EMPOWER/CS, csmon. 

Jf you see the following response: 

mon: not found 

then your UNIX shell path variable (path for csh users) does not include the 
directory where Monitor has been installed 

If the correct directory is / us r/ empower, you would enter. 

For Bourne Shell users: 

$ PATH=/usr/empower/bin:$PATH export PATH 

For C Shell users: 

$ set path={ $path /usr/empower/bin ) 
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Monitor begins operating in an interactive view mode which displays status 
information in tabular format. When you begin a monitoring session, View 1 will 
appear on screen. 

Example view modes for each monitoring tool follow: 
For EMPOWER: 



L V3.1.8 (c) PERFORMIX, Inc. 1995 
Scriptld Sorting A Interval 5 

LastRcv 

[4hr country. A [ [41 A H A [ [A A H A H A H A [ [An 
hto come to the aid A [ [41 A M A [ [B A [ [K 
hto come to the aid A [ [41 A M A [ [B A [ [K 
A [[K A [[4hfor all good men A [[41 A M 
[[4hfor all good men A [ [41 A M A [ [B A [ [K 
A H~ A [ [B A H~ A [ [B A H- A [ [B A H- A [ [B A H~ A [ [H 
6\344\240wo\355e\356 A [\333\2641\210 
[A A H A H A H A [ [An A [ [4h and women A [ [41 A H 



For EMPOWER/X: 



Fri Apr 16 16:41:51 EMPOWER/X MONITOR V4.1.4 (c) PERFORMIX, Inc. 1995 

View 1 of 10 Script 2 of 4 Running Scriptld Sorting A Interval 5 

Scriptld Script State CI LastXmit LastRcv 

ul scriptl keystring 2 Mls A Mdate A Mwho A Mpwd A Mt /Xstuf f A J [empower@nomad] 
u2 scriptl textrcv 2 A Mls A M eryc ode . Jeff A Jqueryc ode . S 

u3 scriptl disconnect 1 <LEFT_ALT> PPPPPPPPPPPPP 

u4 scriptl textrcv 2 A M1 s A Mdat e A Mwho A M 6 10 : 18 A J [empower ©nomad] 



Mon Feb 11 10:43:16 

View 1 of 7 Script 1 of 8 



Scriptld 
userl | 
user2 | 
user3 | 
user4 | 
userB | 
user6 | 
user7 | 
user8 1 



Script 

manager | 

typist | 
manager | 

typist | 

typist | 
manager | 
manager | 

typist | 



State 
xmit 
xmit 
think 
rev 
rev 
xmit 
rev 
xmit 



EMPOWER MONITOP 
Running 

La s tXmi t 



country. A [kkA and w 
^H A H A H A Hof their cou 
o come to the aid A M 
A Mfor all good men A M 
A Mfor all good men A M 
A Mvi A MiNow is the ti 
ry . A [ kkA and women ^ [ 
. A [kkA and women ^ [ : q 
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For EMPOWER/CS: 



Wed Jan 4 15:33:43 

View 1 of 7 Script 1 of 4 



Scriptld 
userl 
user2 
user3 
user4 



_Script State 

foo type 

foo event 

foo event 

foo type 



EMPOWER/CS MONITOR VI . 0 (c) PERFORMIX , Inc. 1995 

Running Scriptld Sorting A Interval 5 



Last Event 

<SysKeyPress> James Smith 
<SysKeyPress><Lef tButtonPress> 
<SysKeyPress> 
<SysKeyPress>test .dat A M 



_CurrentWindow 
Employee 
Run 
Help 
Save As 



63 Monitor Help Screens 

You will begin your Monitor session in view mode. From this mode you can type 
to display the help menu listing Monitor commands. The help menu is displayed 
in three help screens. You can press the space bar to toggle between the help 
screens or press a V to exit the help screen. The three help screens for the 
EMPOWER Monitor are shown below. 

(/Vote; Some of these commands may not appear on the Monitor help screens for 
EMPOWER/X and EMPOWER/CS which only list the commands particular to those 
products.) 



Moving, 



h left 

j down 

+ down 

k up 

- up 

1 right 

nv to view n 

nG to script n 

G to last script 

H highest on screen 

M middle of screen 

L last on screen 



Scrolling 

A u half screen up 
A d half screen down 
A f screen forward 
A b screen backward 
A e one script down 
A y one script up 

Escaping, 



i 

T 
E 
V 
Z 



shell 

trace script 
edit script 
view log 
zoom to script 



Press Spacebar to see next help, q to quit help. 



Searching 

/ search 

\ reverse search 

n next search 

| filter out scripts 
Other 

A [ forget input 

A l refresh 

ni set interval to n 
change sort field 
screen capture 
enable display 
quit 
help 
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* 

Deletina 


Killina 


Flushina 


nDD delete n scripts 


nKK kill n scripts 


nFF flush n logs 


Ds delete screen 


Ks kill screen 


Fs flush screen 


De delete exited 


Ka kill all 


Fa flush all 


Resumina 


Suspendina 


Interruptina 


nRR resume n scripts 


nSS suspend n scripts 


nil interrupt n scripts 


Rs resume screen 


Ss suspend screen 


Is interrupt screen 


Ra resume all 


Sa suspend all 


la interrupt all 


nRt set TRESUME to n 




nit set TINTR to n 




Joinina 






JD join on used display 




JJ join on this display 




complete join 




Press Spacebar to see next help, q to quit help... 



Toaales 




dots 


a 


anchor mode 


b 


bars 


c 


compressed 


e 


exit mode 


o 


owner mode 


P 


pause 


r 


relative time 


w 


wrap log before view 


X 


sort order 


Press Spacebar to see 


first help, q to quit help... 



The following sections describe commands you can use during Monitor sessions. 
Many commands accept optional numeric arguments preceding them. Those 
commands are displayed on the help screen with n' preceding the command 
character, where 'n stands for the optional number. 
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6.6 First Help Screen Commands 



6.6.1 Moving 

In view mode, moving commands function similarly to "vP editor commands. 

j , + Move the cursor n scripts down 
k, - Move the cursor n scripts up 

h Change the view to one view to the left wrapping at the end (If 
1 is the current view, h will change the view to View 7.) 

l Change the view to one view to the right wrapping at the end 
(If 7 is the current view, 1 will change the view to View 1.) 

nv Change the view to view n (If the current view is 2, 4v will 
change the view to view 4. The default value for n is current 
view + 1.) 

nG Move the cursor to the nth script scrolling as necessary (The 
default value for n is last) 

h Move the cursor to the highest script on the current screen 

m Move the cursor to the middle script on the current screen 

L Move the cursor to the last script on the current screen 
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6.6.2 Scrolling 

The scrolling commands operate similarly to "vi" editor commands: 





Move up a half screen 




Move down a half screen 


A f 


Move forward a full screen 


A b 


Move backward a full screen 




Move one script down 


A y 


Move one script up 



Note: You can not scroll the screen when using the V command which pauses 
Monitor. 



6.63 Searching 

The searching commands search for specified data within the current sort field If 
you enter an incorrect search key, you can use the backspace key to remove it For 
this command, n' is the letter n and does not designate a number. 

/ Forward search 
\ Backward search 

n Next search (Search for the next item in the same direction as 
the previous search.) 

If you try to search when paused, the following message will appear 

Can't search when paused 
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If the searched-for data cannot be found (make sure you are searching for data in 
the current sort field), the following message is displayed: 

Not found below in <scriptid> column 

If you specify next search but have not performed a previous search, the following 
message will appear 

No previous search pattern 



6.6.4 Escape Modes 

The escape commands allow you to enter modes external to the view mode without 
quitting your Monitor session. After exiting an escape mode, you will return to 
view mode. The shell escape mode allows you to escape temporarily to a UNIX 
shell to execute shell commands; trace allows you to trace a script source code 
while the script executes; edit allows you to edit the script source code at the 
current execution location; view allows you to flush the script's log file buffer and 
view the log file; and zoom, only available for mon, displays the current screen of a 
script. 

The escape commands are: 

! shell escape mode command 

T trace escape mode command 

E edit escape mode command 

V view escape mode command 

Z zoom escape mode command (only available for mon) 
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The zoom escape mode works only if the following function is in your script source 
file: 

Term { ZOOM, VT1 0 0 | LINES 2 4 | AUTOWRAP ) 

You can enter the shell escape mode at any time. To enter other modes, you must 
move the cursor to the required script and press the escape command. 



6.6.4.1 Trace Mode 

When a script has been idle for an unusual amount of time, tracing its execution to 
see where the script is "blocked" can be very useful. The Y command allows you 
to see what line in the script source file the script currently is executing. 

Tracing a script assumes that you have used the Beginsourcel) and 
Endsource ( ) functions properly. Beginsource { ) should be the first function 
executed whenever a script branches to a new source file. Endsource ( ) should be 
executed just before a return. Beginsource ( ) requires an argument - the name of 
the source file without the .c extension. Endsource { ) has no argument. Source 
files may be nested. 

While tracing a script, you can use the "?" command to get the trace mode help 
menu: 





_Trace Help_ 


p 


toggle pause 


ni 


set interval to n 


A l 


refresh 


1 


toggle line numbers 


? 


help 


q 


quit 



Press q to quit help... 
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Six commands are available in trace mode: 

p Pauses the cursor (Tracing will stop temporarily until the p command 
is pressed again.) 

ni Sets the update interval to n seconds 

A l Refreshes the trace screen 

l Displays the source script's line numbers on the trace screen 

(Pressing the 1 command again will turn the line number display off.) 

? Displays the help menu 

q Quits the Trace mode or quits the Help menu 



6.6.4.2 Edit Mode 

The 'e' command allows you to invoke the "vi" editor on the script source file. The 
"vi" editor must be located either in /usr/bin/vi, or your unix $path ($path for 
csh users) must include the location of "vi". 

When entering the edit mode, the cursor will be placed on the line currently 
executing. Once you have entered the edit mode, you are in the vi editor's 
command mode. You must know how to operate the "vi" editor before using the 
edit mode. 

Note: Any changes made to the script will be included only after you recompile the 
script with the Cscc command and then execute it. 



6.6.4.3 View Mode 

When a script has been idle for a long duration, looking at the script's log file is 
useful. The v command requests that the script flush its log file buffer before 
invoking the UNIX view command on the log file. Since the v command will cause 
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the script to flush its buffer, it may not be necessary for you to specify the 
Set (nobuf ) function in your script. This will increase performance during multi- 
user tests since Set {nobuf ) will cause the script to flush the buffer frequently. 



6.6.4.4 Zoom Mode 

The z command can display the screen image of an emulated user (Only available 
for the Monitor for EMPOWER). The screen image is a snapshot of what a user 
would see if he or she were running the script in display mode at a terminal. 

Before the zoom can occur, the user being "zoomed" must have been updating a 
copy of the screen initiated with the Term( ) function in a script. The first argument 
to Term( ) must be zoom, and the second must describe the terminal that the 
system under test (SUT) thinks it is updating, for example, Term (zoom, 
vtioo | LINES24 1 autowrap) . The script will interpret the escape sequences sent to 
it and maintain a copy of the user's screen. 

Valid terminal types for the TermO function are vtioo, VT220, WYSE50, wyse60, 
and ANSI. 

Frequency of the screen image is determined by the zoom interval, which is every 
five seconds by default This interval can be changed by using the "i" command 
within the zoom mode. 





_Zoom Help_ 


p 


toggle pause 


ni 


set interval to n 


A l 


refresh 




help 


q 


quit 
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Five commands are available in the EMPOWER Monitor's zoom mode: 

p Pauses the screen image (The screen update will stop temporarily until 
the p command is pressed again.) 

ni Sets the update interval to n seconds 

A l Refreshes the zoom screen 

? Displays the help menu 

q Quits zoom mode or quits the help menu 



6.6.5 Other Commands 



6.6.5.1 1 

A [ (Esc) can be used to ignore input such as a typed number that you wish to 
discard 



6.6.5.2 1 

v 1 (control-L) refreshes the screen. 



6.65.3 ni 



ni sets the display interval to n seconds. The display will be repainted with current 
information every n seconds. The default interval value is five seconds, the 
maximum interval value is 3,600 seconds, and the minimum is one. If you specify 
an interval value exceeding the maximum, the interval will be set to the maximum 



EMPOWER/CS Vl.0.1 



6-20 

Copyright PERFORMIX, Inc © 1995 



User's Guide-Multi-User Testing 



value. If you specify an interval value less than the minimum, the interval will be set 
to the default. When sorting by a field that may change often, we suggest that you 
do not set the time interval to a small value (such as li, 2i, or 3i). 



6*6.5.4 s 

s allows you to change the sort field (located on the second line of the header in 
Monitor) to a field on the current view. The default sort field is Scriptid where all 
the scripts will be listed by Scriptid. You can use the h and 1 keys to cycle through 
available fields. The * [ (Esc) key can be used to abort changing the sort field. Once 
you have selected the right field, press the Enter key to re-sort. Monitor pauses 
while the sort field is being selected. 

When sorting on a field other than Scriptid, the Scriptid is used as a secondary 
sort field Scripts will be sorted by the primary sort field first, and any scripts in 
which the primary sort field values are equal will be sorted again by the Scriptid. 
An exception to this process occurs when sorting by idle time; scripts that are in 
the "exit" state or the "suspend" state are sorted to the bottom since idle time is 
not applicable for these scripts. These scripts are sorted by ScriptiD at the bottom 
of the list (Le., after all scripts in other states). 

To watch those scripts that are not progressing as anticipated, sorting by idle time 
is common. Scripts in a Rev state with considerable amounts of idle time may be 
encountering problems on the SUT that need to be fixed If your script is in a think 
state listed under the state column, idle time is expected. 

Monitor displays a "snapshot" of what occurs in executing scripts, but script data 
changes constantly. For this reason, scripts may appear out-of-sort if data changes 
between the times data are sorted and painted on the screen. Also, time values are 
displayed as hh : mm : ss . hh where hh indicates hundredths of a second When 
sorting by time values, and the times grow so that hundredths of a second no 
longer display, scripts may seem out of sort because the time values appear the 
same but scriptids are not in order. Although the hundredths value is not displayed, 
it continues to be used for calculating the sort order. 
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If a script runs for more than 24 hours, sorting by start time may seem out of order 
because the date portion of the time is not displayed. 

Whenever many scripts appear to have completed execution, you may want to sort 
by state or statePattern to help you isolate scripts that have terminated 
abnormally. Sorting by either of these fields while scripts execute is meaningless 
(and somewhat annoying) because data changes so often that it is obsolete as soon 
as it displays. 



6. 6.5*5 C 

c allows you to capture the current screen into a specified file. You will be 
prompted with the file name the first time you issue the c command in the current 
session. The next time you invoke the c command, the current screen will append 
to the specified file. 



6.6.5.6 d 

d enables the display option for a script in the Monitor for EMPOWER. You can 
specify a port to watch the script execute on a separate terminal. The display option 
operates differently for the EMPOWER/X and EMPOWER/CS products. Refer to 
Sections X for details on operating the EMPOWER/X and EMPOWER/CS Monitor 
displays. 

The display tty is included in View 4 under the Display field. 

To initiate the display mode, move the cursor to a script in Monitor and enter the d 
command. Then, enter the name of a display TTY. You can specify a real TTY, for 
example /dev/tty04, or a pseudo TTY, for example /dev/ttypl, where /dev is 
optional. The base name of the TTY used for display mode can be found in Monitor 
View 4. 
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To terminate display mode, enter the d command and press return, but without 
entering a name when prompted for a TTY. 

You should display to a terminal of the same type used by the emulated user. For 
instance, if the SUT is sending escape sequences to the script destined for a 
VT100, you should display to a terminal that can interpret these sequences. 

You can initiate display mode for a script that has been updating a copy of the 
screen itself, that is, it executed Term (zoom, . . . ). When you initiate display 
mode for such a script, a copy of the screen will be sent to the TTY which will make 
the display as current as possible — you will not have to wait for the application on 
the SUT to refresh the screen. 

The Term ( ) function instructs EMPOWER to maintain a run-time screen image for 
use by any of the screen receive functions. This function also allows script 
execution to be viewed with the Zoom mode. 

The syntax of Term ( ) is: 

Term(ZOOM, VT100 | LINES2 4 | AUTOWRAP) ; 

The default Term() function placed in a script specifies nozoom. The other 
parameters depend on the terminal type used when creating the script and specify 
the initial state of the terminal. Valid parameters are LINES24 or LINES25 and either 
autowrap or noautowrap, with LINES24 and autowrap as the default 



6.6,5.7 q 

q quits from any help menu or quits the Monitor session. 
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6.6.5.8 ? 

? displays the help menu. 



6.7 Second Help Screen Commands 



6.7,1 Deleting 

When scripts complete execution, you can use the delete commands to remove 
them from shared memory which allows you to focus only on those scripts that are 
still running. To delete a script, you must either be the script owner or super-user 
and the script must be in the "exit" state. 

Syntax for the delete commands is listed below. 

nDD Delete n scripts starting with the current script (The default value 
for n is one.) 

Ds Delete all scripts on the current screen that belong to you 
De Delete all scripts in the "exit" state that belong to you 

If you do not own the script you attempt to delete, the following message will 
appear on the third line of the header 

Not owner! 

If you specified an nDD command where n is too large, you will see the following 
message: 

Not that many scripts 
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If no scripts were found, the following message will appear: 

Nothing to delete! 
If you tried to delete a running script, the following error message is displayed: 

Script not exited! 

If you attempted a Ds or De command and no exited scripts were found, the 
following message will be displayed 

No exited scripts ! 



6.7.2 Killing 

The kill commands can be used to "kill" currently executing scripts. To operate this 
command, the script must be executing (not exited), and you must be either the 
owner of the script or the super-user. The kill command sends a signal to the 
running script and the script will enter the "exit" state. 

nKK Kill n running scripts starting with the current script (The default 
value for n is one.) 

Ks Kill all running scripts on the current screen that belong to you 

Ka Kill all running scripts that belong to you 

If you specify the kill command but do not own the script, the following warning 
message will be displayed: 

Not owner! 
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If you are the owner but the script is in the "exit" state, kk will display the following 
message: 

Script is already dead I 

If no scripts are running, Ks or Ka will display the following message: 

No live scripts ! 



6.7.3 Flushing 

By default, each script performs buffered writes to its log file to increase 
performance during multi-user tests. The flush commands can be used to signal a 
script to flush its log file buffer which is useful if you are browsing through logs 
and need to see the most recent information in the log. The V command requests 
that the script flush its log file automatically before invoking the UNIX view 
command 

The syntax for the flush commands is listed below. 

nFF Flush n running scripts starting with the current script (The 
default value for n is one.) 

Fs Flush all running scripts on the current screen that belong to you 

Fa Flush all running scripts that belong to you 



6.7.4 Resuming 

Once a script is suspended, you can resume it using commands from Monitor or 
Mix. When resuming more than one script from Monitor, the scripts will resume in 
the background at intervals specified by the nRt command. When resuming from 



EMPOWER/CS Vl.0.1 



6-26 

Copyright PERFOHMIX, Inc. © 1995 



User's Guide-Multi-CIser Testing 



the Mix prompt, the scripts will resume according to the time specified in the Mix 
variable tstart (See Mix Section 2.x for more information). 

nRR Resume n suspended scripts (The default value for n is one.) 

Rs Resume all suspended scripts in the current screen that belong to 
you 

Ra Resume all suspended scripts that belong to you 

nRt Set the resume interval to n seconds (The default value for n is 
five.) 



6.7.5 Suspending 

You may suspend a script while it executes if you are the owner of that script 
Once a script is suspended, it will remain suspended until it is resumed. 

nss Suspend n scripts (The default value for n is one.) 

ss Suspend all scripts on current screen that belong to you 

Sa Suspend all scripts that belong to you 



6.7.6 Interrupting 

Your script may become blocked in a receive state during your EMPOWER 
Monitor session. If so, you can interrupt the script with the interrupt commands. 
Interrupting will force a timeout in the script, and the script will continue if possible. 
If you have set a large timeout value, interrupting is useful if you do not want to 
wait for the timeout interval to expire before executing subsequent script 
transactions. 
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The syntax for the interrupt commands is listed below. 

nil Interrupt n blocked scripts starting with the current script (The 
default value for n is one.) 

is Interrupt all blocked scripts on the current screen that belong to 
you 

la Interrupt all blocked scripts that belong to you 

nit Set the interrupt interval (The default value for n is zero.) 

If you interrupt a script that is not blocked, you will receive the following message: 

Script is not in a rev state! 



6.7.7 Joining 

The Join feature of Monitor (which applies only to the Monitor for EMPOWER) 
allows you to become the emulated user of a blocked script You simply select a 
script and your display will become that of the emulated user. You can interact with 
the application on the SUT in an attempt to revive it, determine what went wrong, 
or simply put the application back on track so the script can continue. With the Join 
feature, you will not have to abort tests simply because one or two scripts fail, and 
developers who need to resolve problems that occur only under load can debug 
them while a test continues. All keystrokes entered during the join are recorded so 
you can incorporate them for subsequent script runs. 

A script can be joined in three ways: Two ways are from Monitor and are 
performed dynamically; one way is from within the script and occurs at a 
predetermined location. These methods are discussed in more detail in the 
following sections. Before a join from Monitor can occur, a script must be blocked 
in a receive state or be suspended. You can use the ss command from mon to force 
a script to suspend if it does not reach a blocked state voluntarily. 
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6.7.7.1 Joining from Monitor 

To begin a joined session in Monitor when the script is in display mode (initiated 
with the -d or -D option of the script, or with the d command of mon), you can 
move the cursor to the script and type Jd (which stands for join display). The joined 
session will begin on the real or pseudo display terminal You now can move to the 
terminal and begin typing. 

A script will pause until you end a joined session by typing "~ at the terminal. The 
script then will return to its previously blocked state. If the script was suspended, 
you can resume it with the rr command of mon. If the script was blocked, you can 
force a timeout with the n command of mon, thereby completing a Rcv( ) . An 
interrupted script will not exit with n, even if the timeout condition was set to 
exit, but will continue as though the timeout condition was set to continue. You 
must enter the kk command to force a script to exit. 

If a script is not in display mode, you can begin a joined session in Monitor with the 
jj command. In this case, the Monitor display will become the emulated user's 
display. The Monitor display will clear, and if the script was executed with a 
Term { zoom , . . . ) function, the emulated user's display will be presented to you. 
You then can begin typing, ending the joined session with "~ . H . If the script was 
not executed with Term (zoom, . . . ), the display will remain blank and you must 
enter a command that will force the application to refresh its display. 

note: You should join a script only from a terminal that is the same type set by the 
emulated user on the SUT. Output from the SUT and the function keys that you 
enter will work only when the terminal types are consistent 



6.7.7.2 Joining from within a Script 

You can join a script in a predetermined location by including the Join ( ) function 
in a script. When your script encounters the Join( ) function, a joined session 
will begin. Such a script must be executed in the foreground, preferably with the -d 
or -d option, because Join ( ) will be ignored if the script runs in the background 
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Keystrokes that you enter during a joined session are recorded in a . x file with the 
prefix "mon . " followed by the script's scriptid. The scriptid is taken from the Mix 
table, the -s option of the script, or the name of the script if it was run from the 
command line. If an . x file exists, the keystrokes will be appended to the file. 

The keystrokes and responses that occurred during a joined session will be built 
into a portion of the corresponding script. The script's prefix will be "mon." 
followed by the script ID with a . c extension. EMPOWER will attempt to group the 
keystrokes into logical transactions. If the . c file exists, the new portion of the 
script will be appended to the file. You can use the . x or . c files built during the 
joined session to aid in patching a script so that it can handle new behavior from an 
application on the SUT. 



6.8 Third Help Screen Commands 

The toggle commands affect overall operation of Monitor. 

converts all two-character control characters to dots making the 
screen easier to read and allowing more data to fit on the screen. 

a anchors the script. The < sign is used to indicate an anchored 
script and is displayed in the column between the Scriptid and 
the Script name. When sorting on fields that often change, the 
anchor is useful for continuing to monitor a particular script 

b adds a vertical line between fields to discriminate more easily 
between columns of data. If the screen will be repainted often, 
do not use this command because printing the column separator 
will slow painting the screen. 

c compresses all views of one script onto the screen. To choose a 
script to compress, move the cursor to that script and press V . 
For mon and csmon, press V again to toggle back to the original, 
uncompressed view of all scripts. For xmon, press V a second 
time to remove blank lines. If your screen originally was not 
large enough to display information from all 10 xmon views, this 
process will allow you to view more of the current script's status 



EMPOWER/CS Vl.0.1 



6-30 

Copyright PERFORMIX, Inc. © 1995 



User's Guide-Multi-CIser Testing 



information. Then, you can press V a third time to toggle back 
to the original, uncompressed xmon view. The compress 
command is useful for monitoring all information of a single 
script To look at the compressed view of another script, simply 
move the cursor to the appropriate script. 

e toggles exit mode. The default mode displays all scripts. The 
alternate mode displays only executing scripts. This command 
allows you to focus on scripts that are still running without having 
to sort through "dead" scripts or delete scripts from shared 
memory. 

o toggles owner mode. The default mode displays all user scripts. 
The alternate mode displays only scripts that belong to you. 

p pauses display, since script information changes often. You may 
move to another script when paused, but you cannot scroll the 
screen. The ? (help) command also will pause Monitor. 

r toggles between absolute and relative times. This is useful when 
displaying timestamps in view 5 of mon and csmon and view 6 of 
xmon. 

w toggles between wrapping and not wrapping logs before 

viewing. Wrapping is useful if your log includes responses from 
the SUT which are too long to be viewed by a system editor or 
which contain unprintable characters. 

x toggles between ascending ( A ) and descending (v) sort order. 



6.9 Views 

Seven different views are available for mon, ten are available for xmon, and seven 
for csmon. Each view displays a screen with a table of information for all scripts 
currently running or recently exited and all views display information for the same 
set of scripts. Each script requires one line on your screen. If you have more 
scripts than lines on your screen, you can scroll to the remaining scripts. 
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The first two lines of each view represent the header which includes the date, 
product information, view number, script number, current state, current sorting 
field, current sorting order, and the update interval. The third line displays 
messages for your information as you execute commands. The fourth line of each 
view contains headers for the different displayed fields . 

When Monitor starts, it enters view mode in a "Loading" state until it has initialized 
to begin monitoring. Next, it will go into a "Waiting" state until it has scripts to 
monitor. As scripts begin to execute, it will go into a "Running" state. Other possible 
states are "Paused" and "Sorting". These states are displayed in view mode. 



6,9-1 EMPOWER Monitor Views 

The seven views available in the Monitor for EMPOWER (mon) are described in 
this section. 
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6.9.1.1 EMPOWER Monitor View 1 

View 1 of mon displays the state of each script and the data transmitted and 
received by each script 



Mon Feb 11 10:43:16 

View 1 of 7 Script 1 of 8 



EMPOWER MONITOR V3 . 1 . 8 (c) PERFORMIX, Inc. 1995 

Running Scriptlci Sorting A Interval 5 



Scriptld Script State LastXmit 

userl | manager] xmit | country. A [kkA and w 

user2 j typist | xmit | A H A H A H A Hof their cou 

user3 | manager j think j o come to the aid A M 

user4 j typist) rcvj A Mfor all good men A M 

user5 | typist j rcv| A Mfor all good men A M 

user6 j manager] xmit j A Mvi A MiNow is the ti 

user 7 j manager j rev j ry . A [kkA and women A [ 

user 8 j typist j xmit j . A [kkA and women A [ : q 



Las tRc v 

[4hr country . A [ [ 41 A H A [ [A A H A H A H A [ [An 
hto come to the aid A [ [41 A M A [ [B A [ [K 
hto come to the aid A [ [41 A M A [ [B A [ [K 
A [[K A [[4hfor all good men A [ [41 A M 
[[4hfor all good men A [ [41 A M A [ [B A [ [K 
A H~ A [ [B A H- A [ [B A H~ A [ [B A H- A [ [B A H~ A [ [H 
6\344\240wo\355e\356 A [\333\2641\210 
[A A H A H A H A [ [An A [ [4h and women A [ [41 A H 



scriptld A unique identifier specified in the script table and used by 
the Mix tool (If you run a script from the command line, the 
scriptld will be the same as the script name.) 

Script The name of the compiled script (The source version of the 

script typically is found in script . c . ) 

state The current state of the scripts execution (xmit, rev, 

suspend, think, and exit) 

LastXmit The last characters transmitted to the SUT by the script 

(Characters scroll from right to left as they are transmitted so 
that the rightmost character is the last character transmitted) 

LastRcv The last characters received from the SUT by the script 

(Characters scroll from right to left as they are received so 
that the rightmost character is the last character received) 



Monitor enforces that scriptid's are unique by allowing a script to "steal" the 
Monitor slot of another script having the same Scriptld. If you run one load test 
after the first is completed, the second run will "re-use" the first Monitor slots. Users 
must be careful to designate different script IDs. 
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Sorting by State is useful when most scripts are in the same state or entering the 
same state, as when scripts are exiting or suspending. 

When many control characters are displayed, entering ' . f (dot) mode will allow more 
characters to be displayed in the Lastxmit and LastRcv fields. 
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6.7.1.2 EMPOWER Monitor View 2 

View 2 of mon displays detailed information of script execution states, idle time, and 
the number of warning and timeout messages for each script. This view often is 
used for debugging scripts. 



Mon Feb 11 10:47:37 EMPOWER MONITOR V3 . 1 . 8 (c) PERF0RMIX, Inc. 1995 

View 2 of 7 Script 1 of 8 Running Idle Sorting v Interval 5 
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StatePattern Additional information relative to the script execution 

state, such as the string being transmitted (xmit), the 
string being looked for (Rev), the current think value 
(Think), or the exit status (exit) 

The time, in seconds, that the script has been idle or 
the time since the shared memory segment was last 
updated by the script 

The number of EMPOWER warnings issued to the 
script (early pattern matches, etc) 

The number of EMPOWER timeouts issued to the 
script (i.e. when an expected rev string never arrives) 

ToCondition The number of seconds before a timeout will occur 

and the action to be taken upon timeout 



Idle 



M NWarn 



NTo 
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6.9.13 EMPOWER Monitor View 3 

View 3 of mon displays script execution completion percentage, the script source 
file name, the log file name, the communication port used by the script, and any 
script notes. 



Fri Apr 16 14:04:45 EMPOWER MONITOR V3 . 1 . 8 (c) PERFORMIX , Inc. 1995 

View 3 of 7 Script 1 of 4 Running Scriptld Sorting A Interval 5 
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Line The line in the script source (.c) file currently executing 

NLine The number of lines in the source (.c) file 

Pet The percentage of script completion 

Source The name of the script source file (may be a function source file) 

Log The log file to which the script is writing 

Port The port on the RTE through which the script is communicating 

Note A user-defined note placed in the script by using the Note ( ) 

function (A note can be placed at any location in the script and 
changed as appropriate.) 
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6.9.1.4 EMPOWER Monitor View 4 



View 4 of mon displays general information about the scripts, such as the owner of 
the script, think time distribution, type rate, and the amount of I/O traffic 
information. I/O information can be used in workload analysis. 



Fri Apr 16 14:05:20 
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Pid 
Owner 

NCXmit 

NCRcv 

IO 

Type 
Disp 



The process ID of the script 

The log in ID of the script's owner, (i.e., the person who 
started the script) 

The total number of characters transmitted to the SUT 

The total number of characters received from the SUT 

I/O ratio of the script or the number of characters 
received for every one character transmitted 

The typing speed of the script 

The display terminal, if applicable 



ThinkTime The think time distribution and parameters 
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6.9.1.5 EMPOWER Monitor View 5 

View 5 of mon displays times of various events as well as elapsed time information. 
Users often can estimate load test completion time by looking at this view. 



Mon Feb 11 10:54:06 EMPOWER MONITOR V3 . 1 . 8 (c) PERFORMIX, Inc. 1995 

View 5 of 7 Script 4 of 8 Running Scriptld Sorting A Interval 1 
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The time script execution began 

The time of the most recent Suspend ( ) in the script 

The time the script resumed execution after a Suspend { ) 

The time of Beginscenario { ) execution, usually before any 
transactions are executed 

The time of Endscenario ( ) execution 

The time of script completion 

The time elapsed since the most recent script activity (If a 
script is exited, it will indicate the time since exiting. If a script 
has begun a scenario, as shown above, it will indicate the time 
elapsed since the scenario was started) 



Start 
Suspend 
Resume 
BeginSc 

EndSc 

Exit 

Elapsed 
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6.9.1.6 EMPOWER Monitor View 6 



View 6 of mon displays function response times as functions complete. With this 
view, users often can determine how the SUT is handling the workload. 



Mon Feb 11 10:51:11 
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The number of functions completed (Each function is a set of 
transactions.) 

Average response time of functions completed 

The last function completed (LastFn and CurrFn will be 
displayed only when you specify a BeginFunction { ) and 
EndFunction( ) pair.) 

The response time of the last function completed 

The function currently executing 

The response time of the function currently executing 



NFn 

AveFnRt 
LastFn 

LastFnRt 

CurrFn 

CurrFnRt 
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6.9.1.7 EMPOWER Monitor View 7 



View 7 of mon displays transaction response times as transactions complete. 



Mon Feb 11 10:52:10 
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The number of transactions xmi t ( ) -Rev { ) pairs completed 

The average response time of transactions completed 

The last transaction completed (LastXr and CurrXr will be 
displayed only when you specify a BeginTransaction ( ) and 
EndTransaction( ) pair.) 

The response time of the last transaction completed 

The transaction currently executing 

The response time of the transaction currently executing 
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6.9.2 Monitor Views for EMPOWER/X 

The ten views available in the Monitor for EMPOWER/X (xmon) are described in 
this section. 



6.9.2.1 EMPOWER/X Monitor View 1 

View 1 of xmon displays the state of each script and the data transmitted and 
received by each script. 

Fri Apr 16 16:41:51 EMPOWER/X MONITOR V4 . 1 . 4 (c) PERFORMIX, Inc. 1995 

View 1 of 10 Script 2 of 4 Running Scriptld Sorting A Interval 5 



Scriptld Script 



State CI 



LastXmit 



LastRcv 



ul scriptl keystring 2 Mls*Mdate^Mwho~Mpwd A Mt /Xstuf f A J [ empower @nomad] 

u2 scriptl textrcv 2 A Mls A M erycode . Jef f ^Jquerycode . S 

u3 scriptl disconnect 1 <LEFT_ALT> PPPPPPPPPPPPP 

u4 scriptl textrcv 2 ^Mls A Mdate A Mwho A M 6 10 : 18M [ empower @nomad] 



scriptld A unique identifier specified in the Mix script table (If you 
run a script from the command line, the Scriptld will be 
the same as the script name.) 

Script The name of the compiled script (The source version of 

the script is typically found in script. c.) 

state The current state of the script's execution (keystring, 

textrcv, suspend, think, or exit) 

ci The active client (application) on the SUT 

LastXmit The last characters transmitted to the SUT by the script 

(Characters scroll from right to left as they are transmitted 
so that the rightmost character is the last character 
transmitted) 

LastRcv The last characters received from the SUT by the script 

(Characters scroll from right to left as they are received so 
that the rightmost character is the last character received) 
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Monitor ensures that Script ids are unique by allowing a script to "steal" the 
Monitor slot of another script having the same Scriptid. If you run a load test 
again after the first run has completed, the second run will "re-use" the previous 
load test's Monitor slots. Users must be careful to designate different script IDs. 

Sorting by state is useful when most scripts are in the same state or entering the 
same state, as when scripts are exiting or suspending. 

When many control characters are displayed, entering ' . 1 (dot) mode allows more 
characters to be displayed in the Lastxmit and LastRcv fields . 
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6.9.2.2 EMPOWER/X Monitor View 2 



View 2 of xmon displays detailed information of script execution states, idle time, 
and the number of warning and timeout messages for each script. This view often 
is used for debugging scripts. 
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Additional information relative to the script execution 
state, such as the string being transmitted (keystring), 
the string being looked for (rev), the current think value 
(think), or the exit status (exit) 

The time, in seconds, that the script has been idle, or the 
time since the script last updated the shared memory 
segment 

The number of EMPOWER/X timeouts issued to the 
script (i.e. when an expected rev string never arrives) 

The limit of the number of EMPOWER/X warnings and 
timeouts issued before script termination 

ToCondition The number of seconds before a timeout will occur 

and the action to be taken upon timeout 
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6.9.23 EMPOWER/X Monitor View 3 



View 3 of xmon displays client information for each script, including the current 
client and the last messages received from the client and the X server. 



\ 



Fri Apr 16 16:41:29 EMPOWER/X MONITOR V4 . 1 . 4 (c) PERFORMIX, Inc. 1995 

View 3 of 10 Script 2 of 4 Running Scriptld Sorting " Interval 5 
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NCI The number of clients in the script 

Seq The script location (line number) of the current message 

LastSMsg The last message (event) sent from the X server to the 
client 

LastCMsg The last message (request) received from the X client on 
the SUT 
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6.9.2.4 EMPOWER/X Monitor View 4 



View 4 of xmoh displays the script execution completion percentage as well as 
mouse and display information. 
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Line The line in the script source (.c) file currently executing 

NLine The number of lines in the source (.c) file 

Pet The percentage of script completion 

Segment The segment currently executing 

x The x-coordinate of the mouse pointer 

Y The y-coordinate of the mouse pointer 

Display The name of the X-window where the executing script is 
displayed 
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6.9.2.5 EMPOWER/X Monitor View 5 

View 5 of xmon displays general script information such as the script's process ID, 
the owner of the script, think time distribution, and user-defined notes. 



Fri Apr 16 16:41:35 EMPOWER/X MONITOR V4 . 1 . 4 (c) PERFORMIX, Inc. 1995 

View 5 of 10 Script 2 of 4 Running Scriptld Sorting A Interval 5 
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pid The process ID of the script 

Owner The log in D of the owner of the script (i.e. the person 

who started the script) 

Conn The connection number used by the executing script 

Log The log file to which the script is writing 

Type The typing speed of the script 

ThinkTime The think time distribution and parameters 

Note A user-defined note placed in the script by using the 

Note ( ) function (A note can be placed at any location in 
the script and changed as appropriate.) 
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6.9.2.6 EMPOWER/X Monitor View 6 



View 6 of xmon displays times of various events as well as elapsed time. Users 
often can estimate load test completion time by looking at this view. 



Fri Apr 16 16:41:37 EMPOWER/X MONITOR V4 . 1 . 4 (c) PERFORMIX, Inc. 1995 

View 6 of 10 Script 2 of 4 Running Scriptld Sorting * Interval 5 



Scriptld Script Start _Suspend Resume _BeginSc 

ul scriptl 16:40:54 .90 

u2 scriptl 16:40:54 .33 

u3 scriptl 16:40:56 .51 

u4 scriptl 16:40:58 .30 



_EndSc Exit _Elapsed 

41.90 
41.94 
39.64 
38.19 



start The time script execution began 

Suspend The time of the most recent suspend ( ) in the script 

Resume The time the script resumed execution after a suspend ( ) 

BeginSc The time of Beginscenario ( ) execution, usually before 
any transactions are executed 

Endsc The time of Endscenario ( ) execution 

Exit The time of script completion 

Elapsed The time elapsed since the most recent script activity (If a 
script exited, it will indicate the time since exiting. If a 
script has begun a scenario, it will indicate the time 
elapsed since the scenario was started) 
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6.9.2.7 EMPOWER/X Monitor View 7 



View 7 of xmon displays function response times as functions complete. With this 
view, users often can determine how the SUT is handling the workload 



Fri Apr 16 16:41:39 EMPOWER/X MONITOR V4 . 1 . 4 (c) PERFORMIX, Inc. 1995 

View 7 of 10 Script 2 of 4 Running Scriptld Sorting " Interval 5 
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u2 scriptl 
u3 scriptl 
u4 scriptl 



NFn _AveFnRt 



LastFn LastFnRt 



CurrFn CurrFnRt 

shell_cmds 2 . 63 

shell_cmds 9.91 
she 1 l„cmds 13.51 
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NFn The number of functions completed (Each function is a set 

of transactions.) 

AveFnRt Average response time of functions completed 

LastFn The last function completed (LastFn and CurrFn will be 

displayed only when you specify a BeginFunction( ) 
and EndFunction( ) pair.) 

LastFnRt The response time of the last function completed 

CurrFn The function currently executing 

CurrFnRt The response time of the function currently executing 
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6.9.2.8 EMPOWER/X Monitor View 8 



View 8 of xmon displays transaction response times as transactions complete. 



Fri Apr 16 16:41:41 
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The number of transactions KeyString ( ) -TextRcv ( ) 
pairs completed (e.g. data base queries, UNIX shell 
commands) 

The average response time of transactions completed 

The last transaction completed (LastXr and CurrXr will 
be displayed only when you specify a BeginTransaction ( ) 
and EndTransaction{ ) pair.) 

The response time of the last transaction completed 

The transaction currently executing 

The response time of the transaction currently executing 

Mote: NXr, AveXrRt, LastXrRt, and CurrXrRt will have values only when a 
BeginTransaction ( ) -EndTransaction ( ) pair has been specified. 
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6,9.2.9 EMPOWER/X Monitor View 9 



View 9 of xmon displays statistics that indicate the number of events and other 
messages sent by the X clients and X servers. 
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NR 


The number of Request (r) messages sent by the X client(s) 


Nr 


The number of reply (r) messages sent by the X server 


Ne 


The number of event (e) messages sent by the X server 


No 


The number of error (o) messages sent by the X server 


NCMsgs 


The number of messages sent by the X client(s) 
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The number of messages sent by the X server(s) 
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6.9.2*10 EMPOWER/X Monitor View 10 



View 10 of xmon displays the number of bytes of messages sent by the X clients 
and the X servers. 
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The number of bytes of the Request (r) messages sent by 
the X client(s) 

The number of bytes of the reply (r) messages sent by 
the X server 

The number of bytes of the event (e) messages sent by 
the X server 

The number of bytes of the error (o) messages sent by 
the X server 

The number of bytes of the messages sent by the X 
client(s) 

The number of bytes of the messages sent by the X 
server(s) 



NRBytes 



NrBytes 



NeBytes 



NoBytes 



NCBytes 



NSBytes 
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6.9.3 EMPOWER/CS Monitor Views 



The seven views available for the Monitor for EMPOWER/CS (csmon) are 
described in this section. 



6.9.3.1 EMPOWER/CS Monitor View 1 

View 1 of csmon displays the state of each script and the data transmitted and 
received by each script 



Wed Jan 4 15:33:43 EMPOWER/CS MONITOR VI . 0 . 1 (c) PERFORMIX, Inc. 1995 

View 1 of 7 Script 1 of 4 Running Scriptld Sorting A Interval 5 



Scriptld 
userl 
user2 
user3 
user4 



.Script State 
foo type 
foo event 
foo event 
foo type 



LastEvent 

< Sys Key Press> James Smith 
< SysKeyPre s s ><Le f t But t onPr e s s> 
<SysKeyPress> 
<SysKeyPress>test . dat^M 



_CurrentWindow 
Employee 
Run 
Help 
Save As 



Scriptld 

Script 

State 
LastEvent 



CurrentWindow 



A unique identifier specified in the script table and used 
by the Mix tool (If you run a script from the command line, 
the Scriptld will be the same as the script name.) 

The name of the compiled script (The source version of 
the script typically is found in a . c file) 

The current state of the script's execution 

The last user interactions transmitted to the database 
server by the script (Characters scroll from right to left 
as they are transmitted so that the rightmost character 
is the last character transmitted) 

The last CurrentWindow ( ) function. 



Monitor enforces that Script ids are unique by allowing a script to "steal" the 
Monitor slot of another script having the same Scriptld. If you run one load test 
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after the first is completed, the second run will "re-use" the first Monitor slots. Users 
must be careful to designate different script IDs. 

Sorting by State is useful when most scripts are in the same state or entering the 
same state, as when scripts are exiting or suspending. 
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6-93.2 EMPOWER/CS Monitor View 2 

View 2 of csmon displays detailed information of script execution states, idle time, 
and the number of database errors and timeout messages for each script. This view 
often is used for debugging scripts. 



Wed Sep 28 14:09:40 EMPOWER/CS MONITOR VI .0.1 (c) PERFORMIX, Inc. 1995 

View 2 of 7 Script 1 of 8 Running Idle Sorting v Interval 1 

Scriptld Script State StatePattern Idle NDBerror NTo NExec NRFetch 

foo foo wrcv SfCoCwAcSfDwPt 1.08 



Additional information relative to the script execution 
state 

The time, in seconds, that the script has been idle or the 
time since the shared memory segment was last updated 
by the script 

The number of database errors issued to the script 

The number of EMPOWER timeouts issued to the script 
(i.e., when an expected windowRcv ( ) never arrives) 

The number of Exec { ) statements in the script that 
were executed, 

The number of fetches from the database after the 

Exec ( ) 



StatePattern 
Idle 

NDBerror 
NTo 

NExec 

NRFetch 
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6.933 EMPOWER/CS Monitor View 3 

View 3 of csmdh displays script execution completion percentage, the script source 
file name, the log file name, the data type used by the script, and amount of think 
time. 



Wed Sep 28 14:09:40 EMPOWER/CS MONITOR VI . 0 . 1 (c) PERFORMIX, Inc. 1995 

View 3 of 7 Script 1 of 4 Running Scriptld Sorting ^ Interval 5 



Scriptld _Script Line NLine _Pct Source 

foo foo 33 63 52.4 foo 



_Log Type_ 



Thinktime 



foo 5.0 uniform 1.0 2.5 



Line The line in the script source (.c) file currently executing 

NLine The number of lines in the source (.c) file 

Pet The percentage of script completion 

Source The name of the script source file (may be a function source file) 

Log The log file to which the script is writing 

Type The typing speed of the script 
Thinktime The think time distribution and parameters 
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6.93.4 EMPOWER/CS Monitor View 4 



View 4 of csmon displays general information about the scripts. 



Wed Sep 28 14:09:40 EMPOWER/ CS MONITOR VI . 0 . 1 (c) PERFORMIX, Inc. 1995 

View 4 of 7 Script 1 of 4 Running Scriptld Sorting A Interval 5 



Scriptld Script Pid Display, 

foo foo 704 ergy 



.Arguments ToCondition 

300 continue 



Note 



Pid The process ID of the script 

Display The display terminal, if applicable 
Arguments The number of arguments to the scripts 

ToCondition The number of seconds before a timeout will occur and the action 
to be taken upon timeout 



Note 



A user-defined note placed in the script by using the Note ( ) 
function (A note can be placed at any location in the script and 
changed as appropriate.) 



EMPOWER/ CS Vl.0.1 



6-56 

Copyright PERFORMIX, Inc. © 1995 



User's Guide— Multi-User Testing 



6.9.3.5 EMPOWER/CS Monitor View 5 

View 5 of csmon displays times of various events as well as elapsed time 
information. Users often can estimate load test completion time by looking at this 
view. 



Wed Sep 28 14:09:40 EMPOWER/CS MONITOR VI . 0 . 1 (c) PERFORMIX , Inc. 1995 

View 5 of 7 Script 4 of 8 Running Scriptld Sorting A Interval 1 



Scriptld 


Script 




Start 


_Suspend 


Resume _BeginSc 




_EndSc 




Exit 


_Elapsed 


userl 


manager 


10: 


45:33 




10:45:33 


10 


:51:10 


10: 


51:10 


2:54.39 


user2 


typist 


10: 


45:48 




10:45:48 


10 


:51:26 


10: 


51:26 


2 :38.50 


user3 


manager 


10: 


46:03 




10:46:03 


10 


:51:41 


10: 


51:42 


2 :23.12 


user4 


manager 


10: 


46:18 


10:53:38 


10:53:46 










18.44 


user5 


typist 


10: 


46:33 




10:46:33 


10 


:52:11 


10: 


52:11 


1:53.86 


user6 


manager 


10: 


46:48 




10:46:48 


10 


:52:26 


10: 


52:26 


1:38.63 


user7 


manager 


10: 


47:03 




10:47:03 










7:02.11 


user8 


typist 


10: 


47:18 




10:47:18 


10 


:52:56 


10: 


52:56 


1:08.41 



The time script execution began 

The time of the most recent Suspend ( ) in the script 

The time the script resumed execution after a Suspend { ) 

The time of Beginscenario ( ) execution, usually before any 
transactions are executed 

The time of Endscenario ( ) execution 

The time of script completion 

The time elapsed since the most recent script activity (If a script 
has exited, the time since exiting will be indicated If a script has 
begun a scenario, as shown above, the time elapsed since the 
scenario was started will be indicated) 



Start 
Suspend 
Resume 
BeginSc 

EndSc 

Exit 

Elapsed 
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6.9.3.6 EMPOWER/CS Monitor View 6 



View 6 of csmon displays function response times as functions complete. With this 
view, users often can determine how the SUT is handling the workload. 



Wed Sep 2S 


14:09:40 




EMP0WER/CS MONITOR VI 


.0.1 (c) 


PERFORMIX, Inc. 1995 


View 6 of 


7 Script 


1 of 8 




Running 


CurrFnRt 


Sorting v Interval 1 


Scriptld 


Script 


NFn 


AveFnRt 


LastFn 


LastFnRt 


CurrFn CurrFnRt 


user7 


manager 










vi 2:43.59 


user2 


typist 


2 


1:27 .23 


vi 


1:26.45 


vi 1:26.09 


user3 


manager 


2 


1:27.08 


vi 


1:26.14 


vi 1:11.20 


userS 


typist 


2 


1:26.98 


vi 


1:25.94 


vi 40.00 


user6 


manager 


2 


1:27.06 


vi 


1:26.01 


vi 25.22 


user8 


typist 


2 


1:26.90 


vi 


1:26.00 




user4 


manager 


1 


3:11.00 


vi 


3:11.00 




userl 


manager 


3 


1:27.47 


vi 


1:28.19 





The number of functions completed (Each function is a set of 
transactions.) 

Average response time of functions completed 

The last function completed (LastFn and CurrFn will be displayed 
only when you specify a BeginFunction ( ) and EndFunction ( ) 
pair.) 

The response time of the last function completed 

The function currently executing 

The response time of the function currently executing 



NFn 

AveFnRt 
LastFn 

LastFnRt 

CurrFn 

CurrFnRt 
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6.9.3.7 EMPOWER/CS Monitor View 7 

View 7 of csmon displays transaction response times as transactions complete. 



Wed Sep 28 14:09:40 


EMPOWER/CS MONITOR 


VI . 0 . 1 


(c) PERF0RMIX, Inc. 1995 


View 7 of 


7 Script 


1 of 8 


Running 




CurrXr Sorting 


v Interval 5 


Scriptld 


Script 


NXr 


AveXrRt 


LastXr 


LastXrRt 


CurrXr CurrXrRt 


user7 


manager 


1 


.13 


vi 


.13 


who 


user8 


typist 


28 


.46 


vi 


.13 


vi 


user6 


manager 


30 


.48 


vi 


.09 


vi .56 


user4 


manager 










date 


userS 


typist 


33 


.49 


Is 


.92 




user3 


manager 


33 


.51 


Is 


.92 




user2 


typist 


33 


.50 


Is 


.92 




userl 


manager 


33 


.51 


Is 


.95 





NXr The number of transactions completed 

AveXrRt The average response time of transactions completed 

LastXr The last transaction completed 

LastXrRt The response time of the last transaction completed 

CurrXr The transaction currently executing 

CurrXrRt The response time of the transaction currently executing 
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7.0 EMPOWER/GV 

As an advanced feature of the EMPOWER products, the EMPOWER/GV tool 
provides additional control over multi-user emulations by creating and controlling 
global variables that are shared among executing scripts. Variables may be defined 
to direct scripts to terminate gracefully when they run an indefinite process, to act 
as a counter for scripts that must perform a fixed amount of work before 
terminating, or to synchronize the execution of multiple scripts. 

Controlling global variables is useful during a multi-user emulation when one script 
depends on another script's actions to execute properly. For example, several 
scripts may delete records from a single database. A global variable can be assigned 
to tell each script which record to delete. Because global variables retain their value 
when script execution has completed, these same scripts can be executed several 
times without resetting the database. 

Global variables also may be used to control access to a commonly used database or 
document For example, several scripts may have to edit a common word 
processing document. If multiple scripts attempt to edit the same document, 
problems may occur. You can define a global variable to protect a document while 
one script edits it Other scripts attempting to edit the document must wait until the 
first script has finished and the global variable "unprotects" the document. 

The Global Variable library permits variables to be shared among scripts. Access to 
and manipulation of global variables is provided at the UNIX driver's shell prompt 
by Global Variable commands and from within scripts by Global Variable functions. 
Commands can create and remove variables. Both commands and functions are 
used to assign values to variables, read the value of a variable, test the value of a 
variable, and protect a variable. 

Note: A knowledge of C language is useful when using Global Variables because 
script functions that access global variables are actually C language statements. 
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7.1 Additional Installation and Environment Setup 

The EMPOWER/QV software is installed automatically when the EMPOWER, 
EMPOWER/X, or EMPOWER/CS software is installed After an EMPOWER 
product has been installed successfully, the following steps will complete 
EMPOWER/QV installation (Note: These steps assume you install the software in 

/ usr / empower): 

Log in to your system as the user who owns the EMPOWER software. This user 
typically is empower or root. 

Set your shell environment variable equal to the directory in which the EMPOWER 
O software was installed 

~& If you are a Bourne-shell user, execute: 

yB $ EMPOWER=/usr/empower 

$ export EMPOWER 

if If you are a C-shell user, execute: 

nj $ setenv EMPOWER /usr/ empower 

0 Then, execute the following command 

$ EMPOWER/bin/gvinstall 

If the in command on your system allows symbolic linking, you can save some disk 
space by executing: 

$ EMPOWER/bin/gvinstall -s 
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7.2 Architecture 

EMPOWER/GV consists of three parts: 

O Global Variables which are created and stored in the shared memory of the UNIX 
script driver 

O Global Variable Commands which are executed from the shell prompt on the 
UNIX script driver to access variables 

O Global Variable Functions which are placed in the script ,c file to allow a script to 
access a variable during script execution 

Global variables are created by a Global Variable command (gv_init) and stored in 
the shared memory of the UNIX script driver. This shared memory is accessible by 
both Global Variable commands and functions, A variable remains in shared 
memory until it is removed and it will retain its value after script execution. If the 
UNIX script driver is rebooted, all global variables are removed. Since global 
variables are stored in shared memory, your system must have the System V 
Shared Memory Facility installed to use the Global Variables tool. 

You can enter Global Variable commands at the shell prompt of the UNIX script 
driver terminal. These commands also may be used during script execution with 
the Mix tool. Global Variable functions are placed in a script .c file during editing 
and can be used only when the script is compiled with Sec, Xscc, or Cscc. (note: 
For EMPOWER or EMPOWER/X users, scripts executed with Preview or 
Xpreview will not recognize the Global Variable functions.) 

Global Variable commands and functions are used to create, allocate, read, update, 
test, and protect global variables. Changes to the value of a variable are made 
immediately. You can update a variable by assigning a new value or by applying a 
mathematical operation to the current value of the variable. You may test the value 
of a variable and use it in conjunction with the C language while statement so that 
an operation continues while the variable has a certain value. You also may protect a 
variable with a Global Variable command or function so that it can be accessed only 
by the script that protected it. 
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7.3 Global Variable Commands 

Global Variable commands are UNIX shell commands used from the shell prompt on 
the UNIX script driver and from shell scripts to control global variables. They control 
access to a variable, read the current value of a variable, specify a new value for a 
variable, test the value of a variable, and control the shared memory segment used 
by global variables. All Global Variable commands begin with M gv_. M 

When a Global Variable command accesses a variable, the operation completes 
before any other command or function may access the variable. (Note: This 
uninterrupted operation is referred to as "atomic" referencing.) 

When a Global Variable command (except for gv_test) executes successfully, the 
return code is set to zero. If a command results in an error, an error message is 
printed to the standard error output destination, or stdout, which is usually the 
UNIX script driver. With the exception of the gv__test command, an error will set 
the return code to one. 

If you enter a command with an improper number of arguments, a usage message 
displays the correct syntax of the command 

Syntax help for each command can be obtained by entering the command name 
followed by a hyphen: 



$ gv_add - 

Usage : 

gv_add name value 

$ 
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7.3.1 Valid Test Relations 

Valid test relations used for relational comparisons in Global Variable commands are 
listed below: 



Equality Relations 
Relation String 



it ^ ii 



Relation Test 

variable equal to value 

variable NOT equal to value 

variable less than value 

variable less than or equal to value 

variable greater than value 

variable greater than or equal to value 



Bit-Wise Relations 

Relation String 



Relation Test 

variable AND value 

variable NOT AND value 

variable OR value 

variable NOT OR value 

variable EXCLUSIVE OR value 

variable NOT EXCLUSIVE OR value 



Logical Relations 
Relation String 



n *p ii 



Relation Test 

variable is non-zero (non-NULL for str) 
variable is zero (NULL for str) 



73.2 Valid Variable Types 

Many variable types are supported by the Global Variable Library. The name of the 
type is used as a parameter in the gv_init command. EMPOWER/GV includes 
support for type name aliases which allows a shorter type name to be used. 
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The valid types, aliases, and descriptions of variable types are listed in the following 
table: 



Type Name 


Alias 


Description 


char 


[none] 


character 


unsigned char 


uchar 


unsigned character 


int 


[none] 


integer 


unsigned int 


uint, unsigned 


unsigned integer 


short int 


short 


short integer 


unsigned short 


intushort, ushort 


unsigned short integer 




int, unsigned short 




long int 


long 


long integer 


unsigned long int 


ulong, ulong int, 


unsigned long integer 




unsigned long 




float 


[none] 


single precision floating point 


double 


long float 


double precision floating point 


string 


str 


character string 


parallel 


par 


parallel global variable 



The maximum length of a string is 32 characters. 



Variable type "parallel" refers to parallel Global Variables. Parallel global variables 
allow a specified number of scripts in a multi-user emulation to execute a series of 
transactions at the same time. All other scripts in the emulation will block while the 
first scripts are working in parallel The blocked scripts wait until the parallel scripts 
have completed execution. 

Note that only the following commands may access Global Variables of type 
"parallel": gv_init, gv_setparallel, gv_getparallel, gv_parallel, 
gv_unparallel, gv_stat, and gv_rrru 
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You must initialize the global variable as parallel type and then set it to a certain 
number of users (scripts) that will execute a series of transactions in parallel. You 
are allowed to set up to five parallel global variables and they must be initialized 
before you initialize any other global variables* 



7.33 Access Control 

The Global Variable commands for access control are gv_init, gv_rm, 
gv_protect, and gv_unprotect. These commands are described below: 

Creates the variable with the specified name, type, and initial value 
(All parallel variables should be initialized before any other 
variables.) 

Removes a variable from shared memory (Variables are 
automatically removed if the system is rebooted) 

Prevents scripts from accessing a variable until the gv_unprotect 
command is entered 

Removes protection from a variable, allowing scripts to access the 
variable 

Errors will occur if you specify the variable type incorrectly, if a variable cannot be 
created, or if you try to remove a variable that does not exist 



7.3.4 Reading a Variable 

The Global Variable commands for reading a variable are gv_read, 
gv_getparallel, and gv_stat. 



f=¥| gv_init 



gv_rm 



gv_protect 



gv_unpro t ec t 
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The gv_read command returns the current value of the specified variable to the 
standard output destination (which is usually the terminal). In the following example, 
3 is the current value of users. 

$ gv_read users 

3 

The gv_getparallel command returns the current value of the specified parallel 
variable. 

Example: 

$ gv_getparallel workers 

n 5 

. r*^ 
™? 

?t The gv_stat command sends to the standard output destination a table showing 

y3 the name, type, and value of the specified variable. The table also shows the 

tf! number of scripts that have allocated the variable and identifies the variable's 

^ protector. For example: 





$ gv_stat users 








EMPOWER/GV V3.1.8, Serial#ROOOOO-000 , 


Copyright 


PERFORMIX, Inc. 1988-95 




Name Type 


Value 


Allocated Protector 




users int 




3 0 NONE 



If gv_stat is executed without an argument, information will be listed for all 
variables: 



$ gv_stat 

EMPOWER/GV V3.1.8, 
Name 


Serial#R00000-000, 
Type 


Copyright 
Value 


PERFORMIX, Inc. 1988-95 
Allocated Protector 


cust 


int 




100 0 CONSOLE 


para 


parallel 




6 0 


f oo 


int 




1 1 
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7.3.5 Updating a Variable 



The Global Variable commands for updating a variable are listed below: 



gv_write 
gv_setparallel 
gv_inc 
gv_dec 

gv_unpar al 1 e 1 

gv_add 

gv_sub 

gvjnul 

gv_div 

gv_mod 
gv_lshif t 
gv_rshif t 
gv_and 
gv_or 
gv_xor 



Assigns a new value to the variable 

Assigns a new value to the parallel variable 

Increases the value of the variable by one 

Decreases the value of the variable by one 

Increases the value of the parallel variable by one 

Adds the specified amount to the current value of the variable 

Subtracts the specified amount from the current value of the 
variable 

Multiplies the current value of the variable by the specified 
amount 

Divides the current value of the variable by the specified 
amount 

Performs a modulo operation on the variable 
Performs a bit-wise shift to the left on the variable 
Performs a bit-wise shift to the right on the variable 
Applies bit-wise AND masking to the variable 
Applies bit-wise OR masking to the variable 
Applies bit-wise EXCLUSIVE-OR masking to the variable 



Each of these commands returns the current value of the variable to the standard 
output destination before performing the specified operation. For example, 
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suppose the variable users has a current value of 5 and you want to make the 
value 6, then change the value by subtracting 4. This interaction would occur as 
demonstrated below: 



$ gv_ write users 6 

5 

$ gv_sub users 4 

6 

$ gv_read users 

2 
$ 



7.3,6 Testing a Variable 

The Global Variable commands for testing a variable are gv_test, gv__waitwhile, 
gv_waituntil, and gv__parallel. These commands compare the current value of 
a variable to a specified value or condition. 

The valid test criteria, specified in Section 73.1, must be either equality, bit-wise, or 
logical relations. For example, the equality relation ">=" tests if the variable value is 
greater than or equal to the specified comparison value. The equality and bit-wise 
relations require that the command include three parameters: the variable name, 
the relation, and a comparison value. Logical relations only require the variable 
name and the relation. 

The gv_test command simply tests the variable as specified. Results of the 
gv_test command are listed below: 

If Comparison Print to Standard Output Set the Return Code to 

is true 1 0 

is false 0 1 

fails due to error error message 2 
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Example: 



$ 


gv__read users 




2 






$ 


gv_test users "==" 


2 


1 






$ 


echo $status 




0 






$ 


gv__inc users 




2 






$ 


gv_read users 




3 






$ 


gv_test users "==" 


2 


0 






$ 


echo $status 




1 






$ 







fiote: $? replaces $ status when displaying the return value for the Bourne shell 
and the Korn shell. 



The gv_waitwhile command waits while the test condition is true. The 
gv_waituntil command waits until the test condition is true. These commands do 
not send a message to the standard output destination. If the command is 
successful, the return code is set to zero. If the variable cannot be referenced, it is 
set to one. The difference between gv_waitwhile and gv_waituntil is 
illustrated below. 



gv_waitwhile{"a M , "<", 3) 

results in: 

a = o -> wait 

a = 1 -> wait 

a = 2 -> wait 

a = 3 -> do not wait 

a = 4 -> do not wait 

a = 5 -> do not wait 



gv_waituntil ("a" , "<", 3) 
results irv 

a = 0 -> do not wait 
a = l -> do not wait 
a = 2 -> do not wait 
a = 3 -> wait 
a = 4 -> wait 
a = 5 -> wait 
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The gv_parallel command waits for a parallel variable to become greater than 
zero then decrements the value of the variable by one. 



7.3.7 Shared Memory Segment Control 

Whenever a Global Variable Command is executed, the necessary shared memory 
segment is created if it does not already exist. The created shared memory 
segment is large enough to support 128 global variables by default. The gv_seg 
command can create a shared memory segment to support fewer or more global 
variables. This command also can remove an existing shared memory segment 
which removes all existing global variables. 

For example, to create a shared memory segment that supports 150 global 
variables, use the following command (assuming a shared memory segment does 
not already exist): 

$ gv_seg 150 

If a shared memory segment already exists, which would be the case if you already 
had executed a Global Variables Command, it must be removed with the -r option 
of gv_seg before a new segment is created: 

$ gv_seg -r 
$ gv_seg 150 

Use caution when removing an existing shared memory segment with gv_seg -r. 
Since removing the shared memory segment removes all global variables, this 
command should not be executed while global variable scripts are executing . 
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7.4 Global Variable Functions 

Global Variable functions act as C language statements to access and control 
variables used by multiple scripts. Scripts with Global Variable functions must be 
compiled with Sec, Xscc, or Cscc before they can be executed. (Note: For 
EMPOWER or EMPOWER/X users, scripts executed with Preview or XPreview will 
not recognize Global Variable functions.) 

Global Variable functions provide features similar to Global Variable commands. 
They control access to a variable, read the current value of a variable, specify a new 
value for a variable, and test the value of a variable. All Global Variable functions 
begin with "Gv_." 

When a Global Variable function accesses a variable, the operation completes 
before any other command or function can access the variable. (Note: This 
uninterrupted operation is referred to as "atomic" referencing.) 

If a Global Variable function can not execute because an error occurred, an error 
message is sent to the standard error destination and the script will exit 

The following error messages occur for any function when the specified variable 
has not been allocated to the script or when the variable does not exist 

Attempt to access a global variable that is not allocated 
Global variable not allocated to this script 
Global variable does not exist 



7.4.1 Access Control 

The Global Variable functions for access control are Gv_alloc { ) , Gv_protect ( ) , 
and Gv_unprotect ( ) . 
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These commands are described below; 



Gv_alloc ( ) Allocates access to a variable 

Gv_f ree ( ) De-allocates access to a variable 

Gv_protect ( ) Prevents other scripts from accessing a variable until the 

Gv_unprotect ( ) function is executed 

Gv_unprotect ( ) Removes protection from a variable, allowing other scripts 
to access the variable 



If a script references a global variable, the Gv_alloc ( > function should be the first 
function in the script The Gv_alloc ( ) function has two parameters: variable name 
and variable type. The variable type must match the type specified when the 
variable was created with the gv_init command. For example: 



Gv_alloc ( "users" , "int" ) ; 



You can de-allocate a global variable with Gv„f ree { ) . If a global variable is not de- 
allocated with Gv_f ree ( ), it automatically will deallocate when the script exits. 

If a script tries to de-allocate a variable that has not been allocated to the script, an 
error will occur. The following error messages occur for any function when the 
specified variable has not been allocated to the script or when the variable does not 
exist: 



Global variable not currently allocated 
Global variable does not exist 



The parameter of the Gv__protect ( ) and Gv_unprotect ( ) functions is the name 
of the variable (e.g., users from the example above). Only the script that protects a 
variable may unprotect it. 
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7,4.2 Reading a Variable 

The Global Variable functions for reading a variable are Gv_read { ) , Gv_readv { ) , 
Gv_getparallel ( ) , and Gv_stat ( ) . The Gv_read ( ) and Gv_readv ( ) functions 
return the current value of a variable. The Gv_getparallel ( ) function returns the 
current value of the specified parallel variable. The Gv_stat{) function supplies 
status information about variables. 

The Gv_read ( ) function returns the current value of the specified global variable. 
Generally, this value is stored in a new variable. For example: 

int curcount ; 

Gv_alloc ( " count " , " int " ) ; 

curcount = Gv_read (" count ") ; 

The value of count is read and stored in an integer variable called curcount. 

The value returned by the Gv_read( ) function is always an integer. If you need to 
use the return value and the actual value of a global variable is not an integer, you 
must use the function name ending with a V to obtain the correct value. In this 
case, an additional parameter is used to indicate where to store the value. 

For example, if you want a script to read the current value of a parameter called 
balance but the value is not an integer, use the Gv_readv( ) function as in the 
following script file excerpt: 

float curbalance; 

Gv_alloc ( "balance" , " float" ) ; 

Gv_readv ( " balance " , &curbalance ) ; 

In this example, the Gv__readv() function retrieves the current value of the 
variable balance and stores it in the floating point variable curbalance. 
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7.43 Updating a Variable 



The Global Variable functions for updating a variable are listed below: 



Gv_write ( ) , 

Gv_writev( ) 

Gv_setparallel ( ) 

Gv_inc ( ) , Gv_incv ( ) 

Gv_dec { ) , Gv_decv ( ) 

Gv_unparallel { ) 

Gv_add ( ) , Gv_addv ( ) 

Gv_sub ( ) , Gv_subv ( ) 

Gv_mul { ) , Gv_mulv ( ) 

Gv_div ( ) , Gv_di w { ) 

Gv_mod { ) , Gv_modv ( ) 

Gv_lshift () , 

Gv_lshiftv() 

Gv_rshif t ( ) , 

Gv_rshiftv() 

Gv_and ( ) , Gv_andv ( ) 

Gv_or ( ) , Gv_orv ( ) 

Gv_xor ( ) , Gv_xorv ( ) 



Assigns a new value to the variable 

Assigns a new value to the parallel variable 

Increases the value of the variable by one 

Decreases the value of the variable by one 

Increases the value of the parallel variable by one 

Adds the specified amount to the current value of the 
variable 

Subtracts the specified amount from the current value 
of the variable 

Multiplies the current value of the variable by the 
specified amount 

Divides the current value of the variable by the 
specified amount 

Performs a modulo operation on the variable 

Performs a bit-wise shift to the left on the variable 

Performs a bit-wise shift to the right on the variable 

Applies bit-wise AND masking to the variable 

Applies bit-wise OR masking to the variable 

Applies bit-wise EXCLUSIVE-OR masking to the 
variable 
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Functions without a trailing V 1 are used for integer variables. Functions with a 
trailing V are used for non-integer variables when the current value of the variable 
is needed The first parameter is the name of the variable for all update functions. 

When an update function is executed, the original value of the variable is saved if 
the variable is an integer, or copied to a pointer location if the variable is not an 
integer. After the operation is performed and the resulting value is assigned, the 
original value of the variable is returned as an integer. 

For example, to assign a new value to the variable count, use the following 
function if count is an integer. 

Gv_wri te ( " count " , 12 ) ; 

To assign a new value to the non-integer variable balance, use: 

float cur balance; 

Gv_alloc { "balance" , " float" ) ; 

Gv_writev( "balance" , 120.75, fccurbalance) ; 

Similarly, the following function can be used to increment the integer variable 

count: 

Gv_inc ( " count " ) ; 

The following statements could be used to increment the non-integer variable 

balance: 

float curbalance; 

Gv_alloc ( "balance" , " float" ) ; 

Gv_incv ( "balance" , &cur balance) ; 

The remaining update functions provide the same capabilities as the corresponding 
Global Variable commands. These functions require an additional parameter to 
specify the operand value. 
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In the following example, the value of the variable count is multiplied by four. The 
value of count prior to multiplication is stored in curcount: 

int curcount ; 

Gv_alloc { " count " , " int " ) ; 

curcount = Gv_mul (" count " , 4) ; 



7.4.4 Testing a Variable 

The Global Variable functions for testing a variable are Gv_test(), 
Gv_waitwhile { ) , Gv_waituntil ( ) , and Gv^parallel { ) . These functions test the 
current value of a variable against a specified value or condition. 

The valid test criteria (See Section 73.1) must be either equality, bit-wise, or logical 
relations. For example, the equality relation ">=" tests if the variable value is 
greater than or equal to the specified comparison value. The equality and bit-wise 
relations require that the function include three parameters: the variable name, the 
relation, and a comparison value. Logical relations only require the variable name 
and the relation. 

The Gv_test ( ) function simply tests the variable as specified Gv_test ( ) returns 
1 if the test is true and 0 if the test is false. For example: 

Gv_alloc ( "quitf lag" , " int" ) ; 
if (Gv_test( "quitf lag" , "==", 1)) 
Exit (1) ; 

The Gv_waitwhile ( ) function waits while the test condition is true. The 
Gv_waituntil ( ) function waits while the test condition is false. These functions 
do not return a value. For example: 

Gv_alloc ( " count " , " int " ) ; 

Gv_inc ( " count " ) ; 

Gv_waitwhile ( "count" , "<", 20); 
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The Gv_parallel { ) function waits for a parallel variable to become greater than 
zero then decrements the value of the variable by one. 



7.5 Using Global Variables Commands and Functions 



7.5.1 Global Variables in Script Execution 

Global variables are accessed by using Global Variable commands and functions 
with the variable name as an argument The format for Global Variable commands is 
gv_name, and for functions, Gv_name ( ) . Both must be used to make effective use 
of global variables. 

The following example demonstrates using a Global Variable command It would be 
entered at the UNIX script driver's command line: 

$ gv_init customer* int 100 

The gv_init command creates a variable with the specified name, variable type, 
and initial value. In this example, gv_init is the Global Variable command, 
customer is the variable name, int specifies that customer is an integer, and 100 
is the initial value of the variable customer. 

To use a variable within a script, you should insert the Gv_alloc { ) function in the 
beginning of the script .c file to access the variable, for example: 

Gv_alloc ( "customer" , "int" ) ; 

The Gv_alloc() function permits the script to access and control the variable 
customer in other global variable functions, for example: 

Gv_protect ( "customer" ) ; 
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Global Variable commands may be used in a Mix command file when a multi-user 
load test is executed with the Mix tool. For example; 



!gv_init users int 0 

use table 

start si s2 s3 

wait 

quit 



When this Mix command file is executed, the Global Variable command gv_init is 
executed as if it was executed from the shell. 



7.5,2 Global Variables Used By Multiple Scripts 

To illustrate the Global Variables concept "atomic referencing," suppose one script 
accesses a variable to perform addition (with the Gv_add() function) and another 
script tries to access the same variable to perform multiplication (with the Gv_mul { ) 
function). The second script will not be able to read or operate on the variable until 
the first script has completed operation. This atomic referencing applies regardless 
of the number of scripts trying to access a variable. Each competing script will wait 
until it can access the variable. 

However, simultaneous access to a set of variables may cause resource contention 
problems in your UNIX kernel when multiple scripts try to access or protect the 
same variable. Problems generally arise from careless use of the Gv_protect ( ) , 
Gv__unprotect ( ) , Gv_waitwhile ( ) , and Gvjwaituntil ( ) functions. 

When a script tries to access a variable protected by another script, it will wait until 
the variable has been unprotected before continuing with execution. 
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A circular protection of variables may result, causing two scripts to pause 
indefinitely, as in the following situations: 

O script one protects variable one 

O script two protects variable two 

O script one tries to protect variable two 

O script two tries to protect variable one 

You always must be aware of the effects that variable protection will have on other 
running scripts. When a variable is to be used by multiple scripts but is protected 
by one script, you should design your scripts so that the variable becomes 
unprotected at some point. Other scripts attempting to read or write to the variable 
will block until the variable is unprotected 

When several scripts employ the Gv_waitwhile () or Gv_waituntil ( ) function 
for the same test condition, some scripts may pause indefinitely. This situation may 
occur because the test condition becomes true (or false) for such a short time that 
some scripts may never see the condition for which they are waiting. 



For example, a script may include the following: 



/* Increment the global variable "users" 


by one 


*/ 


Gv_inc ( "users" ) ; 






/* Wait while "users" is less than 3 */ 






Gv_waitwhile ( "users" , "<" , 3) ; 






/* Decrement the global variable "users" 


by one 


*/ 


Gv_dec ( "users " ) ; 







When the value of users becomes three, this script will return from the 
Gv_waitwhile ( ) function. The value of users then will be decreased by one so 
that its new value is two. If other scripts are using the same Gv_waitwhile ( ) 
function, they may not see the value of users reach three since it is immediately 
decreased by this script Therefore, the other scripts may be blocked indefinitely. 
This error is avoided most easily by designing test conditions that are not true (for 
Gv_waituntil ( ) ) or false (for Gv_waitwhile ( ) ) for only a short time. 
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7.5.3 Setting Type Rate and Think Time With Global Variables 

Global Variable commands and functions can be used to set emulated type rate and 
think time range from the UNIX script driver prior to running a test. Global variables 
are created to specify type rate and minimum and maximum think times. Functions 
in the scripts then use these variables to set type rate and think time range. 

For example, to set the type rate at two characters per second and the minimum 
and maximum values of the think time distribution at one and five seconds, use the 
following Global Variable commands: 

$ gv_init typerate int 2 
$ gv__init thinkmin int 1 
$ gv_init thinkmax int 5 

Then, place the following statements in the beginning of the script .c file: 



Gv_alloc { 11 typerate " , " int" ) ; 
Gv_alloc { " thinkmin" , " int " ) ; 
Gv_alloc ( " thinkmax " , " int " ) ; 

Typerate {Gv_read ( " typerate" ) ) ; 

Thinkunif orm (Gv_read ( " thinkmin" ) , Gv_read { " thinkmax" ) ) ; 



Each time the script is executed, a new type rate and think time distribution may be 
specified If the Typerate () and Thinkunif orm ( ) functions are placed within a 
loop in the script, new values may be set as the script executes. 



7.5.4 Examples 

The following sections present introductory examples for using global variables. 
For simplicity, the example scripts shown in the following sections are EMPOWER 
scripts. Global variables also may be used in EMPOWER/X and EMPOWER/CS 
scripts. 
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7.5.4.1 Externally Initialized vs. Internally Initialized Variables 

Global variables generally are created at the UNIX script driver (i.e., externally 
initialized) with the gv_init command, then accessed in a script with the 
Gv_alloc() function: 



Gv_alloc ("users" , "int" ) ; 
Gv_inc ( "users " ) ; 
Gv_waitwhile{ "users" , "<" , 3); 



To run this script three times, you could enter the following commands at the UNIX 
script driver: 



$ 


gv_init 


users int 


0 




$ 


script 


rlogin: sut 


si 


& 


$ 


script 


rlogin: sut 


s2 


& 


$ 


script 


rlogin: sut 


s3 


& 



The script may be set up so that the variable users is initialized inside the script 



Gv_alloc ( "users " , " int " ) ; 

Gv_j?rotect ( "users " ) ; 

if <Gv_test ("users" , "==" , 3)) 

Gv_write { "users " , 0 ) ; 
Gv_unprotect ( "users " ) ; 
Gv_inc ( "users n ) ; 
Gv_wai twhile { " users " < " , 3 ) ; 



This script may then be run three times with the following transactions at the UNIX 
driver machine (assuming the value of users remains 3 between script runs). The 
gv_init command is not required at the start of the test 

$ script rlogin: sut si & 
$ script rlogin: sut s2 & 
$ script rlogin: sut s3 & 
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7.5 A2 Synchronizing With gv ^protect 



In this example, three scripts are started and synchronized by accessing a variable 
protected at the UNIX driver machine with the gv_protect command. The scripts, 
called si, s2, and s3, include the following statements: 



Gv_alloc ( " synch" , " int " ) ; 
printf("%s ready\n", argv[0]); 
Gv_inc ( " synch" ) ; 
Xmit ( " " ) ; 



Rev ( " . 



) ; 



The following example demonstrates the interaction at the UNIX script driver that 
will execute the scripts: 



$ gv_init synch int 0 
$ gv protect synch 
$ gv_stat 

EMPOWER/GV V3.1.8, Serial #ROOOOO-000 , Copyright PERFORMIX , Inc. 1988-95 
Name Type Value Allocated Protector 



int 



0 



0 



synch 
CONSOLE 
$ si & 
[1] 3058 
si ready 
$ s2 & 
[2] 3060 
$ s3 & 
[3] 3062 
s2 ready 
s3 ready 
$ gv_stat 

EMPOWER/GV V3. 1.8, Serial#R00000-000 , Copyright PERFORMIX , Inc. 1988-95 
Name Type Value Allocated Protector 

synch int 0 3 

CONSOLE 

$ gv_unprotect synch 
$ gv_stat 

EMPOWER/GV V3. 1.8, Serial#R00000-000 , Copyright PERFORMIX, Inc. 1988-95 

Type Value Allocated Protector 



Name 



synch 



int 



3 NONE 
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7.5.43 Unique Numbers 

In this example; a global variable provides unique numbers for a set of scripts that 
delete records from a database. Since the global variable maintains its value after 
the scripts have executed, the scripts may be run multiple times without resetting 
the database. 

This example uses the gv_init command and the Gv_alioc ( ) and Gv_inc { ) 
functions. The gv_init command creates the desired global variable and sets the 
initial value. The Gv_alloc ( ) function permits the script to use the variable and 
ensures that the variable type specified in the script matches the type specified in 
the gv_init command. The Gv_inc() function reads the current value of the 
variable and increments it by one. 

First, the global variable customer is created at the command line on the UNIX 
script driver. The variable is an integer and the initial value is 100: 

$ gv_init customer int 100 

The following script source code deletes five records from the database: 



/* dbdelete.c */ 
Empower ( ar gc , ar gv ) 
int argc; 
char *argv[] ; 
{ 

int i ; 

int this customer; 
char buf [10] ; 

Thinkuniform(2,5) ; /* think 2 to 5 seconds */ 

/* Allocate the global variable "customer" to this script 

(if "customer" does not exist yet, exit) */ 
Gv_alloc { n customer " , " int " ) ; 
Beginscenario { "dbdelete" } ; 
Rcv("$ "); 

Xmit ( "dbstartup A M" ) ; 
Rev ( " > - ) ; 

(continued on following page ...) 
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/* delete five records from the database */ 
for (i = 0; i < 5; i++) { 

/* get a customer number to use and increment 
for the next script */ 

thiscustomer = Gv_inc ( "customer" ) ; 

sprintf (buf , "%d", thiscustomer); 

Mxmit( "delete " r buf, ,,A M", "■); 
Rev ( " > " ) ; 

} 

XmitC'quit^M") ; 

Rcv("$ '* ); 

Xmit( tt exit A M") ; 

Rev ( "connection closed. A J" ) ; 

Endscenario ( "dbdelete" ) ; 

} 



Two scripts containing this source code are executed. The first script is run with 
the display option (-d) which is shown below: 





$ dbdelete -d rlogin: 


Silt si & 




$ dbdelete rlogin :sut 

$ 


s2 & 




Welcome to SUT 






$ dbstartup 






Speedy Database started 


at 12:56:01 EST 10/07/90 




> delete 100 






record for customer 100 


deleted 




> delete 102 






record for customer 102 


deleted 




> delete 103 






record for customer 103 


deleted 




> delete 105 






record for customer 105 


deleted 




> delete 107 






record for customer 107 


deleted 




> quit 






$ exit 






connection closed. 
$ 
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The first deleted customer record was 100. The script used the initial value of the 
variable customer and incremented it. The second script then gained access to the 
variable and deleted record 101. When the first script accessed customer again, the 
value was 102. Also note that the first script was able to delete two more records 
(102 and 103) before the second script accessed the variable again. This is possible 
if the second script is delayed, for example, by a think time delay. 

These scripts may be run again without resetting the database. The variable 
customer remains in shared memory with its last value, so the next run of the 
scripts will begin with the most current value of customer. 

To check the current value of a global variable, use the gv_read command at your 
UNIX script driver's shell prompt 



$ gv_read customer 

110 
$ 



If the database is restored prior to running the scripts again and you want to delete 
the first ten records again, customer must be re-initialized before running the 
scripts. You do not need to specify customer as an integer since the variable 
exists (the type (int) is optional); 

$ gv_init customer int 100 

or 



$ gv_init customer 100 



7.5.4.4 Exclusive Access 



In this example, several scripts run word processing operations to edit a file called 
"proposal 1 '. While one script edits the file, a global variable protects the file so that 
other scripts can not access it. When the script completes editing, the file is 
unprotected 
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A global variable is protected with the function Gv_protect{) and unprotected 
with the function Gv_unprotect ( ). In our example, a variable called f iletoken is 
created. When a script starts to edit the file, f iletoken is protected If another 
script has already protected the variable (and is editing the file), the Gv__protect ( ) 
function will be unsuccessful. The script will wait until it can protect the variable and 
begin editing. 

Before the emulation is executed, the variable must be created: 

$ gv_init filetoken int 0 

The value of filetoken is never used because we are protecting (not testing or 
incrementing) the variable. Therefore, its initial value is unimportant. Also, the 
variable does not need to be re-initialized for subsequent runs of the emulation. 

Each script will include lines similar to the following example for the file editing 
session. Editing must be surrounded by the Gv_protect ( } and Gv_unprotect ( ) 
statements which are shown below: 



/ * wordproc_l . c * / 

/* Allocate the global variable "filetoken" to this script 

(if "filetoken" does not exist yet, exit) */ 
Gv_alloc { " filetoken" , " int" ) ; 
Beginscenario { "wordproc_l" ) ; 
Rcv("$ "); 

/* do some transactions - not detailed here */ 
Xmit ( " cd documents A M" ) ; 



Rcv("$ ") ; 

/* Protect variable "filetoken" from other scripts 

(Only one script can protect filetoken at a time) */ 
Gv_protect ( " filetoken" ) ; 

/* do the exclusive edit - not detailed here */ 
Xmit ( " vi proposal A M" ) ; 

(continued on following page ...) 
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Xmit (" :wq A M") ; 
Rcv<"$ 11 ) ; 

/* Unprotect variable "filetoken" 

(This allows another script to protect "filetoken") */ 
Gv_unprotect { " filetoken" ) ; 
Xmitpexit^M") ; 
Rev { "connection closed. *J"); 
Endscenario ( "wordproc_l " ) ; 



7.5.4.5 Indefinite Benchmark Duration 

In this example, several scripts are designed to run indefinitely so that they may be 
terminated from the UNIX script driver The kill command of Mix does not ensure 
that scripts will terminate gracefully because the script simply disconnects from the 
system under test (SUT). You can assign a global variable that instructs scripts to 
complete the current series of transactions and then quit the SUT application 
before disconnecting. 

To set up this type of script control, each script should be edited to check the 
designated global variable before each series of transactions begins. This 
verification is accomplished by enclosing each series of transactions in a while 
loop and using the Gv_test ( ) function which tests the value of the global variable. 
If the comparison is true, then the script will proceed with the transactions. 

First, the global variable is created: 
$ gv_init workflag int 1 

The variable is given an initial value of 1 The name workflag was chosen because 
the variable specifies whether or not to continue working. 
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The Gv_test ( ) function makes a relational comparison between the value of the 
variable and a specified value. Gv_test ( ) returns the value 1 if the comparison is 
true, and 0 if it is false. 

The following interaction produces these results, using the gv_test command at 
the shell prompt 

$ gv_init a int 5 
$ gv_test a "< n 1 

0 

$ gv_test a 1 

1 

The script code using Gv_test ( ) is shown below: 



Gv_alloc ( "workf lag" , " int" ) ; 
Beginscenario ( "worker" ) ; 
Rev ( " $ " ) ; 

/* enter the SUT application */ 
Xmit { "of f icemail A M" ) ; 
Rcv("om> " ) ; 

while ( Gv_test { "workf lag" , "==", 1) ) { 

/* enter a series of transactions - not detailed here */ 
Xmit ( " " ) ; 



Rcv{ "om> " ) ; 

} 

/* quit the SUT application */ 
Xmit{"quit A M") ; 
Rcv("$ ") ; 

/* exit from the SUT */ 
Xmit("exit A M") ; 
Rev ( "connection closed. A J" ) ; 
Endscenario ( "worker" ) ; 
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Each script in the multi-user test should have some form of this code. Contents of 
the while loop would differ for each series of transactions. When you are ready to 
terminate all scripts, redefine the value of the variable workf lag to be 0 with the 
gv_write command entered at the UNIX script driver: 

$ gv_write workflag 0 

1 

This command will make each script wait until the current series of transactions is 
complete, then quit the SUT application. The system responds to the gv_write 
command with the original value of the variable, 1. 

Before running the scripts again, workflag will have to be reset. You are not 
required to specify workflag as an integer because it already exists: 

$ gv_init workflag 1 

If the value of workflag is not reset, each script would fail the test specified in 
Gv_test ( ) and quit without processing any transactions. 

Use the gv_init command to create a new variable and assign a value to the 
variable. Unless the specified variable currently is alloacted by a script, gv_init 
also can assign a new value to an existing variable. 

By comparison, you can use the gv_write command to assign a new value to an 
existing variable, even if the variable already is allocated by a script 

Therefore, gv_init generally is used between tests, and gv_write is used during 
a test 



75.4.6 Fixed Number of Transactions 

In the following example, a set of scripts will execute a series of transactions a 
specified number of times. As in the previous example, the scripts are set up so 
that the value of a global variable is checked before the transactions execute. 
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A global variable function is created to count down how many times the series of 
transactions executes. The function Gv_dec ( ) is used to decrement the count each 
time the transactions execute. 

First, the variable is created and given the initial value 600, which is the total 
number of times the series of transactions will be executed during the multi-user 
emulation. 

$ gv_init work int 600 

Each script first gains access to the variable work with the Gv_aiioc ( ) function. 
Then, the Gv_dec ( ) function decrements the value of work by one. To determine 
if the new value of work is greater than zero, a test is performed with the while 
statement. If the value of the variable is greater than zero, the contents of the loop 
(the series of transactions) are executed 

Each of these scripts will contain the following: 



Gv_alloc ( "work " , H int " ) ; 
Beginscenario { "worker" ) ; 
Rcv("$ ") ; 

/* enter the SUT application */ 
Xmit ( "of ficemail^M" ) ; 
Rev ( " om> " ) ; 

while (Gv.decpwork" ) > 0) { /* there's work to do */ 

/* enter a series of transactions - not detailed here */ 
Xmit(" "); 

Rcv("om> 11 ); 

} 

/* quit the SUT application */ 
Xmit( M quit A M") ; 
Rcv("$ " ); 

/* exit from the SUT */ 
Xmit{ n exit A M n ) ; 
Rev { "connection closed. A J" ) ; 
Endscenario ( "worker" ) ; 
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Once the value of work becomes zero (i.e., the series of transactions has been 
executed 600 times), each script will terminate as it gets to the while loop. As each 
script falls through the while loop, the value of work is decremented to an 
increasingly large negative number. Since the while loop is set up to execute only 
if work is greater than zero, this negative number creates no problems. 

To run the multi-user test again, the variable work must be reset. If desired, you 
may initialize work to a different value, and you are not required to specify work as 
an integer since it already exists: 

$ gv_init work 120 



7.5.4.7 Script Synchronization 

In this example, a set of scripts is synchronized before the scripts execute 
commands on the SUT. A global variable is created and incremented as each script 
starts. The function Gv_wa it while { ) pauses each script until all scripts have 
started. 

The Gv_waitwhiie() function makes the script pause as long as the specified 
relational comparison is true. When the comparison becomes false, script execution 
continues past the Gv„waitwhile { ) statement 

The global variable that stores the number of executed scripts is initialized: 
$ gv_init users int 0 

Each script first gains access to the variable users with the Gv_alloc ( ) function. 
Then, the Gv.inc ( ) function increments the value of users by one and 
Gv_waitwhile { ) tests the value of users. 
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Each script includes the following: 



/* Allocate the global variable "users" to this script 

(if "users" does not exist yet, exit) */ 
Gv_al loc ( " users " , " int " ) ; 

Beginscenario ( "date test" ) ; 

Rev ( " $ " ) ; 

/* Increment the global variable "users" */ 
Gv_inc ( " users " ) ; 

/* Wait while "users" is less than 3 */ 
Gv_waitwhile ("users", "<" , 3); 

/* do some transactions - not detailed here */ 
Xmit ( "cd documents A M" ) ; 



Rcv("$ ") ; 

Xmit ( "exit^M") ; 

Rcv( "connection closed. " J" ) ; 

Endscenario ( "datetest " ) ; 



To run the multi-user emulation again, the variable users must be reset since it will 
retain a value of three after the first execution. You are not required to specify that 
users is an integer since it already exists. 

Example: 

$ gv_init users 0 
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7.5.4.8 Limited Script Activity in Multi-CIser Emulation 

In this example, parallel Global Variables control execution of multiple scripts. Parallel 
variable commands and functions allow a subset of emulated users to execute a 
portion of the script at a given time. Specifically, during an emulation involving 500 
users, a portion of the test may be executed in parallel by only 50 users. Each user 
will execute one script. The Global Variable worker is created from the UNIX script 
driver shell as a parallel type variable with an initial value of 50: 

$ gv_init worker parallel 5 0 

The following script is executed by all users (some detail is left out for brevity): 



login ( ) 

{/* login transactions - not detailed here */} 

Empower ( ar gc , argv ) 
int argc ; 
char *argv [ ] ; 

{ 

Gv_alloc ( "worker" , "parallel" ) ; 
login () ; 

Beginscenario ( "example" ) ; 

/* ... numerous transactions */ 

Gv_parallel ( "worker" ) ; 

/* ... limited portion of transactions */ 
Gv_unparallel ( "worker" ) ; 
/* ... numerous transactions */ 
Endscenario ( " example " ) ; 

} 
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The first 50 users to reach the Gv_parallel ( ) function during script execution 
immediately will execute the limited portion of transactions. The remaining 450 
users will reach the Gv_parallel ( ) function and will wait 

As the 50th user executes the Gv_parallel { ) function, the value of the variable 
worker is decremented to zero. As each of the first 50 scripts reaches the 
Gv_unparallel { ) function, the value of worker is incremented to be greater than 
zero, so that one of the waiting scripts can execute the limited portion of 
transactions. This process ensures that only the first 50 scripts will execute the 
specified transactions at the same time. 



7.5.4.9 Sharing a File Offset 

Creating scripts to read input files on the UNIX script driver is a common practice. 
Such files contain names, addresses, phone numbers, etc., used for emulating 
database queries and updates. For such an emulation, each user would need unique 
data, so, each script must read from a different file. A test of 100 users would need 
100 input files. Considerable effort often is required to create the 100 files, 
especially if you must run tests with different numbers of users. 

The EMPOWER products provide a convenient way for many scripts to read from 
a single file ensuring that data for each script is unique. You can use the File I/O 
functions (such as Fioreadline O ) in scripts to read and write files. (See Section 
7 Script Content and Enhancement of your Script Development manual for more 
information on File I/O functions.) These functions include a Fioshare { ) function 
which is used to identify files that are to be shared Fioshare ( ) must be called 
before any other File I/O functions are called to reference the same file. 

Fioshare () in a script presumes execution of the fioshare command at the 
UNIX script driver's shell prompt The fioshare command creates a global variable 
that contains the offset for the next byte to be read from a shared file. The value of 
the global variable (offset) remains between tests, so you can continue to read an 
input file from the point left by the previous test Saving the offset in this manner 
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is useful in tests that corrupt a database on the SUT. The ability to avoid the same 
transactions means you do not have to restore the database before every test. 

You must execute the f ioshare command if you want to resume reading from the 
beginning of the input file. For this reason, f ioshare often is run from Mix 
command files that set up for a new test 

For example, assume we require scripts to read commands from the following 
input file cmds: 



date 
who 

Is /bin 
ps -ef 

grep xxx /etc/passwd 



The following command will create the global offset for the file: 
$ f ioshare cmds 

A segment in the script described above might look like the following example. 
Each execution of this script will read different lines. 



Fioshare ( " cmds " ) ; 
Fioreadline { "cmds " ) ; 
while (FIOLEN != -1) { 

Mxmit (FIOBUFFER, " A M", " " ) ; 

Rev ( " $ " ) ; 

Fioreadline ( " cmds " ) ; 

} 



The global offset is stored in a global variable and the global variables name is the 
inode of the shared file. This condition can be confirmed by typing the "is -i" 
command with an argument of the shared file and then running the gv_stat 
command 
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For example: 



$ fioshare cmds 








$ Is -i cmds 








59449 cmds 








$ gv_stat 








EMPOWER/ GV V3.1.8, 


Serial#R00000-000, 


Copyright 


PERFORMIX, Inc. 1988-95 


Name 


Type 


Value 


Allocated Protector 


59449 

$ 


long int 




0 0 



To discontinue sharing a file, the Fiounshare{ ) function and fiounshare shell 
command are used Neither the function nor the command remove the global 
variable offset for the file. They simply mark the global variable as being unusable 
for further File I/O functions. 

The Fiounshare () function disables the sharing of the file offset only for the 
script that executes the function. The fiounshare shell command disables sharing 
of the file offset for all scripts currently sharing the file. 

To remove the global variable offset, you must use the gv_rm shell command to 
remove the global variable named in the gv__stat output listed above. For example: 

$ gv_rm -f 59449 



7.5.4.10 Script Scenario Selection 

For this example, we use a global variable to select types of scenarios to execute. 
Multiple copies of a single script are used and the script contains all of the desired 
scenarios. 
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The test includes a mix of following scenarios: 



Scenario 

receptionist 

database 



Count 
1 user 
3 users 
1 user 



manager 
visitor 



Remainder of users 



A single script with functions containing each set of transactions will implement this 
mix of scenarios. By using a global variable called users, the empower ( ) function 
will select a unique ID for the script Global Variables allow this test to execute 
without passing arguments to the script through the Mix table. 

The Gv_inc { ) function increments the value of users. Before it is incremented, 
the value of users is saved in the local variable myid. Each script has a unique 
value of myid which is used in a switch ( ) statement to select the proper scenario 
to run. 

First, the global variable users is initialized with a zero value. Note: This 
initialization must be performed prior to each run: 

$ gv_init users int 0 

Several copies of the script are started with Mix. The first script to call Gv_inc ( ) 
returns a value of 0 to myid, so it calls the receptionist { ) function. The next 
three (myid values 1, 2, and 3) call the database ( ) function. The next script (myid = 
4) calls the manager ( ) function. The remainder of scripts (myid = 5, 6, etc.) call the 
visitor () function. 

In the following script, the actual transactions for the four scenarios are left out for 
brevity: 
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login ( ) 
{ 

Rev ( "login: " } ; 

Xmit ( "userid^M" ) ; 
Rev ( "word: " ) ; 

Xmit ( "passwd A M" ) ; 

Rev ( " $ ") ; 

} 

manager ( ) 

{ /* manager transactions go here */ } 
receptionist ( ) 

{ /* receptionist transactions go here */ } 
database ( ) 

{ /* database transactions go here */ } 
visitor ( ) 

{ /* visitor transactions go here */ } 

Empower { ) 
{ 

int myid; 

Gv_alloc ( " users " , " int " ) ; 
myid = Gv_inc ( "users " ) ; 

Timeout (30, CONTINUE ) ; 
Thinkuni form (1,3) ; 

login {) ; 

switch (myid) { 

case 0: Beginscenario ( "receptionist ") ; 
receptionist ( ) ; 
Endscenario { "receptionist" ) ; 
break; 

(continued on following page ...) 
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case 1 : 
case 2 : 

case 3 : Beginscenar io ( " database " ) ; 
database ( ) ; 

Ends ceiiar io ( " database " ) ; 
break ; 

case 4 : Beginscenar io ( "manager" ) ; 
manager ( ) ; 

Endscenario ( "manager" ) ; 
break; 

default : Beginscenario ( "visitor" ) ; 
visitor ( ) ; 

Endscenario ( "visitor" ) ; 
break; 

} 

Xmit ("exit^M") ; 
Rev ( " " ) ; 

} 



7.5.4.11 Scripts Controlled By One Script 

In the following example, 11 identical scripts execute simultaneously and are 
controlled by the first executed script. This controlling script will not interact with 
SUT applications so its communication port to the SUT can be specified as 
"pseudorsh -i" on the command line. The controlling script sets the global 
variables that are accessed by the other scripts. 

First, four global variables are initialized: 

$ gv_init control int 0 

$ gv_init quitflag int 0 

$ gv_init users int 0 

$ gv_init duration int 3600 

The first script to call Gv_inc { ) becomes the controller. It pauses (with 
Gv_wait while ( )) while the other ten scripts start As each script starts, this 
controlling script increments the variable users and waits while users is less than 



EMPOWER/CS Vl.0.1 



7-41 

Copyright PERFORMIX, Inc. © 1995 



User's Guide— Multi-Qser Testing 



ten. Once these ten scripts have started, the controller script uses Gv_read ( ) to 
retrieve the value of global variable duration. The controller script then executes a 
Sleep delay for the number of seconds specified by the duration variable. 

All other scripts execute the function do_invoice. This function includes a while 
loop which checks the value of global variable quit flag. If quit flag has the value 
zero, the function continues to execute. 

When the controller script concludes the sleep delay, it increments quit flag, 
causing the other scripts to return from do_invoice. The controller script uses 
Gv_waitwhile { ) to pause until the other scripts have completed* Each of the other 
scripts decrements the variable users. When the value of users is zero, the 
controller script returns from Gv_wa it while ( ) , re-initializes control and 
quit flag, and exits. 

Each script would include the following: 



login ( ) 

{/* login transactions - not detailed here */} 

do_invoice{ ) 
{ 

/* do some transactions - not detailed here */ 
Xmit{" ..."); 



Rcv("$ "); 

} 

Empower ( ) 

{ 

Gv_alloc ( " control " , " int " ) ; 
Gv_alloc ( "quitflag" , "int" ) ; 
Gv_alloc ("users" , "int") ; 

(continued on following page . . . ) 
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if (Gv_inc( "control") ==0) { 
Gv_waitwhile( "users" , "<", 10); 
Gv_alloc ( "duration" , "int" ) ; 
Sleep (Gv_read( "duration" ) ) ; 
Gv_inc { "quit flag" ) ; 
Gv_waituntil { "users" , M ==" , 0) ; 
Gv_write ( 11 control " , 0 } ; 
Gv_write( "users" , 0) ; 
Gv_write( "quit flag" , 0) ; 
} 

else { 
login () ; 

Beginscenario ( " invoice" ) ; 
Gv__inc { " users " ) ; 

while (Gv_test("quitf lag " , »==", 0))/* check for quit indicator */ 
do_invoice { ) ; 

Gv_dec ( "users" ) ; 

Endscenario { " invoice M ) ; 

Xmit ( "exit A M n ) ; 

Rev { "connection closed. A J" ) ; 

} 

} 



7.5.4.12 Scripts With Collective Throughput 

In the following example, scripts use global variables to control throughput of 
transactions the scripts submit to the SUL Script execution is controlled at the shell 
by setting the value of the global variable workf lag. 

First, global variables workf lag and transactions are initialized: 

$ gv_init workflag int 0 

$ gv_init transactions int 0 
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As each script executes, it waits while workf lag has a zero value which allows 
scripts to synchronize before continuing. Continuation is prompted at the shell by 
setting the value of workf lag to one with gv_write. 

When each script returns from Gv_waitwhile { ) , it uses the Time ( ) function to 
record system time in the local variable start time. Then, the script checks 
workf lag with Gv_read( ) and if the value of workf lag is one, enters a while 
loop to begin a transaction. The transaction executes, the variable transactions is 
incremented, and the time is stored in the variable curtime with Time ( ) . 

Gv_read{ ) retrieves the number of transactions in the variable transactions. 
This number is divided by the difference between start time and curtime to 
determine the cumulative throughput for all scripts. If the cumulative throughput 
exceeds the target specified by thruput, the script will execute a sleep delay for 
zero to three seconds. 

Script execution terminates when the shell command gvjwrite resets the value of 
workf lag to zero. 
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An example script follows: 



#define THRUPUT 10.0 /* transactions per second */ 
login { ) 

{/* login transactions - not detailed here */} 

Empower ( ) 
{ 

struct timevalue start time, curtime ; 
Gv_alloc ( " transactions " , " int " ) ; 
Gv_alloc { "workf lag" , " int" ) ; 

Timeout (30, CONTINUE ) ; 
Thinkuni form (1,3) ; 
login ( ) ; 

Gv_waitwhile { "workf lag" , "==", 0) ; 
Beginscenario{ "worker" ) ; 

Time (&s tart time) ; 

while (Gv_test ("workf lag", "==", 1)) { 

/* do a transaction - not detailed here */ 
Xmit(" ..-"); 
Rev { " $ " ) ; 

Gv_inc { " transactions " ) ; 
Time ( & curtime ) ; 

if ( (Gv_read( "transactions" ) / 

Dif f time (&start time, &curtime) ) > THRUPUT) 
Sleep (Range (0, 3) ) ; 

} 

Endscenario ( "worker" ) ; 

Xmit ("exit A M" ) ; 

Rev ( " " ) ; 

} 
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7.5.4.13 Passing SCIT Data to the Next Script 

In the following example, two scripts process transactions with a database 
application. After the first script has completed database operations, a control 
number received from the SUT is saved in a global variable for the second script's 
use. The first script copies the control number from the response buffer rbuffer 
into the global variable mailbox. The second script copies the saved control 
number from the mailbox into a transmit buffer. 

First, the global variable is created at the UNIX script driver: 

$ gv_init mailbox str n B 

The first script includes the following entries. Notice that the control number from 
the SUT is saved in the global variable controlnum. 



char control [GVSTRINGMAX + 1] ; 
Gv_alloc ( "mailbox" , "str" ) ; 

Rev ( " $ " ) ; 

/* do a transaction - not detailed here */ 
Xmit ("..."); 

/* align the control number at the beginning of RBUFFER */ 
Scan ( "Control number is: 11 ) ; 

/* read control number response into RBUFFER */ 
Rcv("$ 11 ) ; 

s t r ncpy ( c on t r o 1 , RBUFFER , 10); 

/* put control number in global variable for script2 */ 
Gv_wr i tev ( " mai Ibox " , contro 1 , ( char * ) NULL ) ; 
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The second script uses the control number string from the first script: 



Gv_alloc ( "mailbox" , "str") ; 
char control [GVSTRINGMAX + 1] ; 

Rcv("$ "); 

/* read the control number string left in the global variable */ 
Gv_readv{ "mailbox" , control) ; 

/* do a transaction with the new string */ 
Mxmit (control, ,,A M ,! , " " ) ; 
Rcv("$ "); 
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1.0 Introduction 

This manual contains technical reference material for the EMPOWER/CS script 
functions and EMPOWER/ GV functions and commands. 

The EMPOWER/CS Script Development and Multi-User Testing Manuals guided 
you through the steps required to create and execute sophisticated load testing 
scripts with EMPOWER/CS. This manual provides reference information to help 
you understand how to use the various script functions and commands available. 



1.1 Organization of the EMPOWER/CS User's Guides 

The complete documentation for EMPOWER/CS includes three user's manuals 
which include general use information, installation instructions, technical reference 
.material, and examples. The following list identifies each user manual: 

EMPOWER/CS Script Development 

Describes how to create and execute scripts to perform realistic load tests on your 
client/ server environment (This process involves using the EMPOWER/CS tools 
Capture and Cscc and editing and enhancing your scripts to make them unique to 
your environment.) 

Multi-User Testing 

Describes how to use the multi-user tools Mix, Extract, Report, Draw, Monitor, and 
Global Variables (GV) for emulating realistic loads and measuring performance data 

EMPOWER/CS Reference 

Describes all commands, functions, and possible error messages for 
EMPOWER/CS (This manual also includes technical support information for 
contacting PERFORMIX, Inc.) 
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1.2 Organization of this Manual 

This Reference Manual is divided into the following sections: 

Section 1: Introduces you to the EMPOWER/CS reference manual 

Section 2: Describes EMPOWER/CS script functions and GV commands 

Section 3: Lists and describes possible warning and error messages 
generated by EMPOWER/CS 

Section 4: Provides information on contacting PERFORM1X, Inc. technical 
support 



1.3 User's Guide Conventions 



The conventions followed in this User Guide are listed below: 



Regular Font 
Arial Font 

Mono- Spaced Font 

Bold Mono- Spaced Font 

[-S scriptid] 
gv__stat (name | -s) 



Used for all regular body text 

Represents the MS Windows environment 

Used for all command, function, and file names; for 
all examples; and, generally, for any computer- 
generated text 

In examples, represents entries made by the 
EMPOWER/CS user 

In command syntaxes, text within these square 
brackets represents optional command parameters 

Vertical lines ( | ) separate command parameter 
choices 

Within scripts, the ellipsis marks indicate that some 
script content was left out for brevity 
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Endfunction ( ) 



Beginscenario { ) 



gv_stat 



Parentheses are included with script functions 
mentioned in regular body text. For most functions, 
one or more parameters will be listed in the 
parentheses. 

EMPOWER/CS script functions use initial 
capitalization 

EMPOWER/CS command names use all lowercase 
letters 



Capture 



When an EMPOWER/CS tool is mentioned within 
regular body text, it is shown in regular font with 
initial caps 



The term, "SLIT" refers to your client/server system under test. The client/server 
SUT includes the database server and the database applications on that server used 
for your emulation. 
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This section provides technical descriptions for EMPOWER/CS script functions 
and EMPOWER/GV functions and commands. All function names begin with an 
uppercase letter and command names begin with a lowercase letter. 

Note: While Global Variable functions are added to a script .c file and can be 
executed only when the script is compiled with Cscc, Global Variable commands are 
entered at the shell prompt of the UNIX driver machine and also may be used 
during script execution with the Mix tool. 

Technical descriptions are presented in the following format: 

FUNCTION or The name of the function or command 
COMMAND 

SYNTAX The syntax of the function or command 

DESCRIPTION A definition of each parameter (if applicable) and a discussion 



of the features of the function or command 



RETURN VALUE 
(if applicable) 



The value of the return code for successful and 
unsuccessful execution of the function or command 



EXAMPLES 



One or more examples showing the use of the function or 
command in the script 



SEE ALSO 
(if applicable) 



A list of related functions or commands 
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Fioreadline ( " info " ) ; 
if (FI0LEN==-1) { 
Fiorewind { " info " ) ; 
Fioreadline ( " info " ) ; 
} 

Type("%s", FIOBUFFER) ; 



SEE ALSO Fioautorewind, Fioclose, Fioseek 
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Endtimer - Record the ending time of a set of database activities 

Eventtime - Retrieve the time of an EMPOWER/CS event 

Exec - Execute the parse 



Fetch - Fetch the specified data from the database 

FetchRaw - Fetch the specified binary data from the database 

Fioautorewind - Automatically rewind the file pointer to the beginning of the 

specified file 

Fioclose - Closes a specified file 

Fiodeiimiter - Define field delimiters for a specified file 

Fioopen - Opens a specified file 

Fioreadchar - Reads n bytes from a specified file 

Fioreadfield - Read the next field from a specified file 

Fioreadfields - Read multiple fields from a specified file 

Fioreadline - Read the next line from a specified file 

Fiorewind - Rewind the file pointer to the beginning of the specified file 

Fioseek - Set the file pointer to a specific byte in the file 

Fioshare - Identifies a file to be shared 

Fioskipchar - Skip forward n characters in the file 

Fioskipfield - Skip forward n fields in the file 

Fioskipline - Skip forward n lines in the file 

Rounshare - Discontinue the sharing of a file 

Fiowritechar - Write n bytes from the buffer to the file 



GetNextRow - Sort through the fetched rows of data 

GetlntVar - Return the current integer value of a specified variable 

GetVar - Return the current value of a specified variable 

gv__add - Add the specified amount to the current value of a variable 

Gv_add, Gv_addv - Add the specified amount to the current value of a variable 

Gv_alloc - Allocate access to a variable 

gv_and - Apply bit-wise AND masking to a variable 

Gv__and, Gv_andv - Apply bit-wise AND masking to a variable 

gv_dec - Decrease the value of a variable by one 

Gv_dec, Gv_decv - Decrease the value of a variable by one 

gv_div - Divide the current value of a variable by the specified amount 

Gv—div* Gv_divv - Divide the current value of a variable by the specified amount 

Gv__free - De-allocate access to a variable 

gv__getparallel - Return the current value of a parallel variable 

Gv qetparallel - Return the current value of a parallel variable 

gv__inc - Increase the value of a variable by one 

Gv_Jnc> Gv_incv - Increase the value of a variable by one 
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gv_init 


Initialize a variable, creating the variable if necessary 




gv Ishift 


Perform a bit-wise shift to the left on a variable 




Gv_lshift, uv_Jshirtv - 


Perform a bit-wise shift to the left on a variable 




gv_mod 


Perform a modulo operation on a variable 




uv_mod, (jv_modv - 


Perform a modulo operation on a variable 




gv__mul - 


Multiply the current value of a variable by the specified amount 




Cjv__mul, <jv_muiv - 


Multiply the current value of a variable by the specified amount 




gv_or 


Apply bit -wise OR masking to a variable 




Gv_pr, Gv_orv 


Apply bit -wise OR masking to a variable 




gv_parallel 


Wait until the value of the variable becomes greater than zero 
then decrement the variable by one 




Gv__parallel 


Wait until the value of the variable becomes greater than zero 
then decrement the variable by one 




gv_protect - 


Protect a variable from access by other users and scripts 




Cjv_protect - 


Prevent other scripts from accessing a variable until the 






Gv__unprotect() function is executed 




gv_read 


Return the current value of a variable 


ffi 


Gv_read, Gv_readv 


T~\ l ii - il C • 1 1 

Return the current value of a variable 




gv_rm 


Remove a variable from shared memory 


%j 


gv__rshift 


Perform a bit -wise shift to the right on a variable 




Gv^rshift, Gvjrshiftv - 


Perform a bit-wise shift to the right on a variable 


tfl 


gv_seg 


Control the shared memory segment 




gv_setparallel 


Assign a new value to a parallel variable 


- 


Gv_setparallel 


Assign a new value to a parallel variable 




gv_stat 


r-k i 1**. l ^ • .i . . p ■ i i 

Return a list showing the status of one or more variables 


y 


Gv_stat 


Return a structure showing the status of a variable 


':" =■£ 


gv_sub 


Subtract the specified amount from the current value of a 






variable 




Gv_sub, Gv_subv 


Subtract the specified amount from the current value of a 


— v? 




variable 




gv__test 


Test if the specified comparison is true 




Gv_test 


Test if the specified comparison is true 




gv_unparallel 


Increase the value of the parallel variable by one 




Gv_unparallei 


1 iL 1 f II 1 1 l i 

Increase the value of a parallel vanable by one 




gv_unprotect 


Release a variable for access by other users and scripts 




Gv_unprotect 


Remove protection from a variable, allowing other scripts access 
to the variable 




gv_waituntil 


Wait until the specified comparison is true 




Gv_waituntil 


Wait until the specified comparison is true 




gv_waitwhile 


Wait while the specified comparison is true 




Gv_waitwhile 


Wait while the specified comparison is true 




gv_ write 


Assign a new value to a variable 




Gv_write, Gv_writev - 


Assign a new value to a variable 
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gv_xor 

Gv_xor, Gv_xorv 



Apply bit-wise EXCLUSIVE-OR masking to a variable 
Apply bit-wise EXCLUSIVE-OR masking to a variable 



Hostname 



Specify the name of the host machine 



InitialWindow 
Inote 



Restore the Windows desktop as captured 
Record a Monitor message (integer) 



KeyDown 
KeyPress 
KeyUp 



Emulate pressing a key 

Emulate pressing and releasing a key 

Emulate releasing a key 



Language 

LeftButtonDown 

LeftButtonPress 

LeftButtonUp 

LeftDblPress 

Log 

Logoff 

Logon 



Specify the language to be used 
Emulate pressing the left button down on the mouse 
Emulate pressing and releasing the left button on the mouse 
Emulate releasing the left button 

Emulate two consecutive presses and releases of the left button 
of the mouse 

Record a message in the log file 

Close the communication link to the database 

Open a communication link to the database 



MiddleButtonDown 
MiddleButtonPress 
MiddleButtonUp 
MiddleDblPress 



Emulate pressing the middle button down on the mouse 
Emulate pressing and releasing the middle button on the mouse 
Emulate releasing the middle button on the mouse 
Emulate two consecutive presses and releases of the middle 
button of the mouse 



Mote 



Record a Monitor message (string) 



Open 
Openenv 



Open a cursor structure 
Open a database environment 
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Paceconstant 
Pacetne 

Paceuniform 

Parse 

Password 

Pause 

Pointerrate 



Set a constant script pace 

Set a script pace defined by a truncated negative exponential 
distribution 

Set a script pace defined by a uniform distribution of two values 

Parse a SQL statement 

Specify the user password 

Pause a transaction in progress 

Set the emulated mouse pointer speed 



Range 

RightButtonDown 
RightButtonPress 
RightfiuttonUp 
RightDblPress 

Rollback 



Produce a random number from the specified range 

Emulate pressing the right button down on the mouse 

Emulate pressing and releasing the right button on the mouse 

Emulate releasing the right button on the mouse 

Emulate two consecutive presses and releases of the right button 

of the mouse 

Rollback all database processing 



Seed 

Servername 
Set 

SetlntVar 
SetVar 
Sleep 
Sql 

SqlExec 

Suspend 

SysKeyDown 

SysKeyPress 

SysKeyUp 



Seed the random number generator 
Specify the name of the server 
Turn on script options 

Specify a new integer value for a specified variable 
Specify a new value for a specified variable 
Suspend script execution for an interval 
Parse a SQL statement 
Execute a SQL statement 

Suspend script execution until a resume signal is received 
Emulate pressing a key with the Alt key 
Emulate pressing and releasing a key with the Alt key 
Emulate releasing a key with the Alt key 



Think 

Thinkactual 

Thinkconstant 

Thinktne 

Thinkuniform 

Time 

Timeout 

Transaction 

Type 

Typerate 



Perform a thinking delay 

Define actual think time distribution 

Define constant think time distribution 

Define a truncated negative exponential think time 

Define uniform think time distribution 

Get the current UNIX script driver machine time 

Specify timeout condition 

Define a database transaction 

Emulate keystrokes entered at the keyboard 

Set the emulated typing speed 
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Unset - Turn script options off 

Username - Specify the name of the user 



WindowRcv - Paint window on screen 
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FUNCTION 



AppName 



SYNTAX 



AppName ( 1 ognum , appname ) 
int lognum; 
char * appname; 



DESCRIPTION Parameters 

lognum The number of the log on structure that will access the SUT 

appname The name of the client application that will interact with the 
SUT 

Comments 

The AppName ( ) function is inserted into the script before a log on 
connection when the name of the client application that will be 
interacting with the SUT is specified. During script execution, the 
AppName ( ) function is used to define the application name a logon 
connection will use to interact with the SUT. Application names help the 
SUT to identify logon connections. 

Note: Because this function is inserted into your script based on how 
the client application interacts with the SUT, you should not attempt to 
edit this function or remove it from the script. If you change this 
function from when it was captured, you may drastically alter the 
expected behavior of the client and SUT and therefore, break the script 
during execution. 

RETURN VALUE If the function is successful, zero is returned If an error occurs, -1 
is returned. 



SEE ALSO 



Hostname, Language, Password, Servername, Username 
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FUNCTION 



AppWait 



SYNTAX 



void AppWait (n) 



double n; 



DESCRIPTION 



Parameters 



n 



The amount of time in seconds taken to draw a window on 



screen 



Comments 

This function is inserted into the script file during Capture to record the 
amount of time taken to draw a window on screen. It also inlcudes the 
amount of application processing time for certain database operations. 
For instance, if the application retrieved and requested the sum of 100 
numbers from the database, the total AppWait { ) would include the time 
taken to add the numbers and the time taken to draw a window. 

The AppWait {) function is used during script execution in Non-Display 
mode to emulate application delay for drawing windows and application 
processing before the emulated user can continue to the next input. 
This function does not apply to Display mode script execution because 
the application actually processes database operations. 

If you wish to change your AppWait delay, you may set a multiplication 
factor with the AppWaitFactor ( ) function. 

This function multiplies the AppWait delay times the factor. For 
instance, if during script execution, you think your application may be 
twice as slow because it is receiving twice as much data from the 
server, you can set the AppWaitFactor ( ) to 2 so that the script will 
emulate the extra delay. 



RETURN VALUE (not applicable) 
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EXAMPLES In the following example, the script recorded an application delay of 

1.16 seconds to draw the Program Manager window. 

AppWait (1.16) ; 

WindowRcv( " SfDwAcSf Sf Sf Pt" } ; 
CurrentWindow (" Program Manager") ; 

SEE ALSO AppWaitFactor, WindowRcv 
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FUNCTION AppWaitFactor 

SYNTAX AppWaitFactor (n) 

double n; 



DESCRIPTION Parameters 

n The multiplying factor for the value of the AppWait delay. 

The default value of n is 1. 

Comments 

The AppWaitFactor ( ) function specifies a multiplying factor for the 
value of the AppWait delay. 

You may insert the AppWaitFactor ( ) function into a script when 
editing. This function applies only to AppWait ( ) functions that occur 
after the AppWaitFactor () function in the script. Multiple 
AppWaitFactor ( ) functions may be inserted into a single script. 

The AppWaitFactor { ) function is particularly useful when an 
increased load on the server could cause increased AppWait delays 
where none occurred in previous script executions. 



RETURN VALUE If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 



EXAMPLES The following example doubles the AppWait ( ) for closing the General 

Ledger window, and sets the AppWait ( ) back to 1 for opening the 
Accounting application: 
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Cur rentWindow ( " General Ledger " 


,20,30,234,234) ; 


ButtonPush( "Close" ,254,261) ; 




AppWait Factor (2) ; 




AppWait (1.6) ; 




WindowRcvC'SfDwAcSfSfSfPt") ; 




CurrentWindow ( " PrograinManager " 


,0,0,1048,1048) ; 


ButtonPush{ "Accounting Application" ,23,45) ; 


AppWaitFactor (1) ; 




AppWait (2.1) ; 




WindowRc v ( " S f CwCwAc SfSfSfSfPt" 


) ; 


CurrentWindow { "Accounting" , 20 , 


40,234,234) ; 



AppWait 
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FUNCTION 



Beginfunction 



SYNTAX 



Beginfunction (str) 



char *str; 



DESCRIPTION 



Parameters 



str 



The name of the function as defined by the EMPOWER/CS 
user. This parameter is null-terminated character string. 



Comments 

The Beginfunction( ) function defines the start of a set of emulated 
activities called a function. 

EMPOWER/CS allows you to place C language functions in the script 
during Capture by selecting the Function button in the Capture window. 
When you define a function, EMPOWER/CS automatically inserts 
Beginfunction { ) and Endf unction ( ) around the function in the 
script file. You also may insert these functions when editing your script 



The functions Beginsource { ) and Endsource ( ) automatically are 
placed around Beginfunction { ) and Endf unction ( ) to prepare the 
specified function as a source file. For instance, during a multi-user 
emulation, you may wish to break a common function out into one 
source file that can be called by multiple scripts. Beginsource ( ) and 
Endsource ( ) specify a file as a source file. 

When a script is executed, EMPOWER/CS places a time stamp with 
each Beginfunction ( ) and Endf unction { ) function so that the 
Report tool can calculate response time statistics for the function. The 
response time data for these functions represents the time required to 
perform all interactions within the function. 

Note that the "function" identified by the Beginfunction ( ) and 
Endf unction ( ) functions is different from the C language concept of a 



file. 
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function. C language functions, which are similar to procedures in Pascal 
and subroutines in FORTRAN, are used to group a set of 
EMPOWER/CS functions and C statements together. They are called 
during script execution. 

RETURN VALUE (not applicable) 

EXAMPLES In the following example, the Beginf unction ( ) and Endf unction ( ) 

statements are placed in a C language function that consists of opening 
a window. The name of the function is openwindow. A function call is 
placed within the scenario and the actual function is listed after 
Endscenario ( ) : 



Empower ( ) ; 
{ 

AppWait (0.33) ; 
WindowRcvf "Sf SfSfPt" ) ; 



openwindow ( ) ; 

LeftButtonDown(132, 91) ; 
LeftButtonUp(158,212) ; 

AppWait {3. 52) ; 
WindowRcvCScSfSfSfPt" ) ; 

Endscenario ( "example" ) ; 
} 

openwindow ( ) 
{ 

Beginsource ( "scriptl) ; 
Beginf unct ion { "openwindow" ) ; 

(continued on following page . . .) 
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LeftDblPress (438, 304) ; 
LeftDblClick(438, 304) ; 



AppWait (0.24) ; 

WindowRcv( " PtCoCwCwDwAcSfCwCoSf CwCwCwCwSf AcPtPtPt " ) ; 
WindowRcv ( " Pt " ) ; 

CurrentWindow { "New. , . " ) ; 

/* Clicked (Button) (Cancel) */ 
LeftButtonDown(342,256) ; 



End function ( " openwindow" ) ; 

Ends our ce ( ) ; 

} 



Timestamps in the log file' will correspond to the BeginfunctionO and 
Endf unction ( ) statements in the script 



Example: 



»> 12 Beginf unction ( "openwindow" ) 14:43:23.01 
»> 27 Endfunctiont "openwindow") 14:43:27.15 



SEE ALSO 



Beginsource, Endfunction, Endsource 
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FUNCTION Beginscenario 



SYNTAX 



Beginscenario ( str) 
char *str; 



DESCRIPTION Parameters 

str The name of the script as defined in the Capture session. 

This name is a null-terminated character string. 

Comments 

The term "scenario" generally applies to a large portion of emulated 
activity. Usually for EMPOWER/CS, a scenario is an entire script 
EMPOWER/CS automatically places Beginscenario ( ) and 
Endscenario ( ) functions at the beginning and end of script activity 
during Capture. 

If you wish to change the str parameter for this function, you may do 
so when editing your script 

EMPOWER/CS provides summary performance information for each 
scenario. For example, the Report tool provides scenario start and stop 
times, duration, throughput, and average response times. 

By default, the duration of the test is determined by the time stamps of 
the first Beginscenario ( ) and of the last Endscenario { ) . 



RETURN VALUE (not applicable) 



EXAMPLES The name of the scenario is taken from the name of the script source 

file. Initiation of capturing the script example would cause the following 
functions to be inserted at the beginning and end of the script 
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Beginscenario { "example" ) 
Endscenario ( " example " ) 

The log file created from script execution will contain time stamps for 
the beginning and end of the scenario. 

Example: 

»> 10 Beginscenario { "example" ) 12:05:29.00 
»> 462 Endscenario ( "example" ) 12:08:23.07 

SEE ALSO Endscenario 
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FUNCTION 



Beginsource 



SYNTAX 



Beginsource (str) 



char *str; 



DESCRIPTION 



Parameters 



str 



The name of the script source file which is a null-terminated 
character string 



Comments 

Modular script design is achieved by storing one or more functions in 
separate script source files, which allows a script to include a function 
call rather than repeating a set of interactions. When each source file is 
compiled with the -c option of the cscc command, an object file for 
each script is created which can be compiled with and linked to the main 
script file. 

If a script is compiled from multiple source files, each source file should 
include Beginsource ( ) and Endsource ( ) statements. Beginsource ( ) 
and Endsource ( ) specify the source file used for script execution. 



When editing your scripts, you should insert the Beginsource ( ) 
function at the source file's entry point, typically just before the first 
executable statement in each function. The Endsource () function 
should be placed at file's exit point, typically just after the last executable 
statement in each function. 

Beginsource ( ) and Endsource () also are placed around the C 
functions defined during Capture. Functions are formatted in this way 
so that for a multi-user emulation you may break the function out of a 
script into a separate source file to be used by multiple scripts. 

The Beginsource ( ) and Endsource ( ) statements are used in Monitor 
to indicate the source file being executed at a certain point of script 
execution. 
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RETURN VALUE (not applicable) 

EXAMPLES In the following example, elements of a function called logof f 1 ( ) 

may be contained in a separate script file called exitapp.c, as shown: 



logof fl() 
{ 

Begins ource ( " exitapp " ) ; 
Beginf unction ( " logof f 1 " ) 

Think(9.05) ; 

LeftButtonDown{207, 97) ; 
LeftButtonUp(226,241) ; 



AppWait (0.33) ; 
WindowRcv ( " ScDwAc " ) ; 

CurrentWindow ( "Capture - scrip tl " , 21 , 690 , 57 , 726 ) ; 
Coiranit (L0G1) ; 



Close (CUR1) ; 

Logof f(LOGl) ; 

C 1 os env (ORACLE) ; 

Endf unction {" logof fl") ; 

Ends ource ( ) ; 

} 



SEE ALSO 



Endsource 
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FUNCTION 



Begintimer 



SYNTAX 



Begintimer ( s tr ) 



char *str; 



DESCRIPTION 



Parameters 



str 



A string that specifies the name of the timer to begin 



Comments 

Begintimer ( ) and Endtimer ( ) are used in a script to measure script 
activity. These functions are time stamped in the executed script's log 
file and are used by Report for measuring response time of the 
specified activity. Begintimer () must have a corresponding 
Endtimer () function and the corresponding functions must have the 
same str parameter. 



The Begintimer ( ) and Endtimer ( ) functions can be nested. 

If the Capture option Insert timer is selected, the Begintimer ( } and 
Endtimer ( ) functions are inserted automatically into the script by 
EMPOWER/CS to measure response time of database traffic. These 
functions will be inserted around database traffic that occurs between 
two user events. A user event such as pressing the Return key on the 
keyboard or activating a pushbutton on screen may initiate database 
activity. The str parameter identifies the user event that initiated the 
database activity. For example, if a pushbutton initiated database 
activity, the parameter to Begintimer ( ) and Endtimer ( ) would list a 
two-level tree structure that lists the parent window and the button. 

The Endtimer ( ) function will occur at the end of the database activity 
when a window is drawn on screen or another set of user input begins. 

These functions also can be user-specified. Similar to the functions 
BeginfunctionO and Endf unction { ), they can be inserted manually 
into the script when editing or by activating the EMPOWER/CS Timer 
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button in the Capture window during Capture. If you select the Timer 
button, Begintimer ( ) is inserted into the script measuring activity until 
the End button is selected to insert Endtimer { ) . 



When editing your script, you may change the str parameter to a string 
that is more meaningful for your emulation. 

RETURN VALUE (not applicable) 

EXAMPLES In the following example, Begintimer ( ) and Endtimer ( ) were 

inserted into the script around database activity. Notice that the 
parameter to these functions lists the last user event, which was 
pressing the OK button in the window titled Status. 



Cur r entWindow { " S t a tus ",240,180,408,301); 
ButtonPushpOK" , 322, 267) ; 

WindowRcv ( " Sf AcSf Dw" ) ; 



Begintimer ( " Status_OK" ) ; 

Close (CUR1) ; 
Logof f (LOG1) ; 
Closenv{ ORACLE) ; 

Endtimer ( M Status_OK" ) ; 



SEE ALSO Endtimer 
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FUNCTION 



BeginTransaction 



SYNTAX 



BeginTransaction ( lognum) 
int lognum; 



DESCRIPTION Parameters 

lognum An identifier of a logon communication structure 

Comments 

The BeginTransaction ( ) function is used to start a transaction in a 
script. This function is inserted into the script when the client 
application instructs the database to begin a transaction. 

The transaction begun with BeginTransaction ( ) can be ended with a 
Commit ( ) or Rollback { ) function. It also can be paused and continued 
with the functions Pause ( ) and Continue ( ) . 

RETURN VALUE If the function succeeds, a zero is returned. If the function fails, a -1 is 
returned. 



EXAMPLES 



The following example defines a transaction: 



BeginTransaction (LOG1 ) 
Open {LOG1, CUR1) ; 

Exec (CURD ; 
Commit (L0G1) ; 



SEE ALSO 



Commit, Continue, Pause, Rollback 
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FUNCTION Bind 

SYNTAX Bind (curnum, name, type, length) 

int curnum; 
char *name; 
int type, length; 

DESCRIPTION Parameters 

curnum An identifier of the cursor structure of the associated SQL 
statement 

name The variable's placeholder name as listed in the SQL 
statement 

~S type " The variable's data type 

^ length The length of the variable in bytes 

J3 Comments 

& If a SQL statement requires data to be input to the database, 

^ placeholders for input variables will be listed in the SQL statement and 

yk are indicated by leading colons. A Bind ( ) function will be inserted into 

P the script for each placeholder that is listed During script execution, the 

L3f Bind{ ) function binds the placeholder to a variable that is to be passed 

S^j to the database. For example, if a select-list item of the SQL statement 

Q includes a placeholder such as rNAME, the BindO function is inserted 

into the script to bind :NAME to a variable. 

BindO associates the address of a script variable with the specified 
select-list item, or placeholder, in the SQL statement The parameters of 
the BindO function bind the variable to its placeholder by a specific 
cursor number, the placeholder name listed in the SQL statement, the 
variable's data type, and the variable's length. 

The BindO function is called after the Parse () statement and before 
Exec ( ) . 
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Note: Because this function is inserted into your script based on how 
the client application interacts with the SUT, you should not attempt to 
edit this function or remove it from the script. If you change this 
function from when it was captured, you may drastically alter the 
expected behavior of the client application and SUT and therefore, 
break the script during execution. 



RETURN VALUE 



If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 



EXAMPLES If an input variable is specified within a Parse ( ) statement, the 

BindO function is inserted into the script instead of Define (). The 
following example demonstrates a Bind ( ) function inserted for the 
variable, x, which was listed in the preceding SQL statement 



Parse (CURl, "SELECT EMPNO, ENAME, JOB, MGR, HIREDATE, 
SAL, COMM, DEPTNO FROM EMP WHERE EMPNO=:X" ); 



Bind{CURl, "X", STRING, 10); 



SEE ALSO 



Bindp, BindDefine, Define 
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FUNCTION BindDefine 

SYNTAX BindDefine (curnum, name, type, length) 

int curnum; 
char *name; 
int type, length; 

DESCRIPTION Parameters 

curnum An identifier of the cursor structure of the associated SQL 
statement 

name The variable's placeholder name as listed in the SQL 
statement 

type The variable's data type 

length The length of the variable 

Comments 

A BindDefine () function is inserted into the script when data is 
passed to and returned from the database as designated in a SQL 
statement During script execution, BindDefine () inputs a specified 
variable to the database and then returns the value of the variable. 

BindDefine () associates the address of a script variable with the 
specified select-list item, or placeholder, in the SQL statement. This 
placeholder is designated by leading colons. The variable is defined by 
the parameters of the BindDefine () function which identify it by a 
specific cursor number, the placeholder name in the SQL statement, the 
variable's data type, and the variable's length. 

The BindDefine () function must be called after the Parse {) 
statement and before Exec { ) . 



As an example, suppose the SQL statement specified that the value for 
:NAME was Smith and it was to be inserted into a record overwriting the 
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existing value, Jones. BindDef ine { ) would specify Smith as the new 
value for the record and then return the old value, Jones, to the variable. 

Note: Because this function is inserted into your script based on how 
the client application interacts with the SUT, you should not attempt to 
edit this function or remove it from the script. If you change this 
function from when it was captured, you may drastically alter the 
expected behavior of the client application and SUT and therefore, 
break the script during execution. 

RETURN VALUE If the function is successful, zero is returned. If an error occurs, -1 is 
returned, 

SEE ALSO Bind, Bindp, Define 
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FUNCTION Bindp 



SYNTAX Bindp {cur num, pos, type, length) 

int cur num; 
char *pos ; 
int type, length; 

DESCRIPTION Parameters 

curnura An identifier of the cursor structure of the associated SQL 
statement 

pos A position index for the variable's placeholder as listed in 

the SQL statement 

type The variable's data type 

length The length of the variable 

Comments 

This function may be inserted into the script instead of a Bind() 
function when a variable referenced in a SQL statement contains data to 
be input to the database. Instead of binding a placeholder name to the 
variable, the Bindp ( ) function binds a variable's position index in a 
SQL statement to the variable. 



Bindp ( ) associates the address of a script variable with the specified 
select-list item, or placeholder, in the SQL statement This placeholder is 
indicated by leading colons. The parameters of the Bindp ( ) function 
identify the variable by a specific cursor number, the position index in 
the SQL statement of the variable's placeholder, the variable's data type, 
and the variable's length. The positions of the select list-items start at T 
for the first (or left-most) select-list item, "2" for the second, etc. 

The Bindp ( ) function must be called after the Parse ( ) statement and 
before the Exec ( ) function. 
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Note: Because this function is inserted into your script based on how 
the client application interacts with the SUT, you should not attempt to 
edit this function or remove it from the script If you change this 
function from when it was captured, you may drastically alter the 
expected behavior of the client application and SUT and therefore, 
break the script during execution. 

RETURN VALUE If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 

EXAMPLES The following example demonstrates BindpO in a script file: 



Parse (CUR1, "select ename from employee_table where 
empno =: empno and deptno= : deptno" ) ; 



Bindp(CURl, 1, STRING, 20); /* pos 1 is : empno */ 

Bindp(CURl, 2, LONG, 4); /* pos 2 is :deptno */ 



SEE ALSO Bind, BindDefine, Define 
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FUNCTION 



ButtonPush 



SYNTAX 



int ButtonPush ( str , x,y) 



char *str; 



unsigned int x,y; 



DESCRIPTION 



Parameters 



str 



The name of the pushbutton or the tree structure that lists 
the pushbutton 



x 



The on screen x coordinate of the pushbutton 



y 



The on screen y coordinate of the pushbutton 



Comments 

The ButtonPush { ) function is inserted in the script file during Capture 
to indicate that a MS Windows pushbutton was activated (such as OK, 
Cancel, Yes, No, etc.). This function is used during script execution in 
Display mode to move the mouse to activate a pushbutton defined in 
the parameter str. In Non-Display mode, this function simulates mouse 
movement as defined in the x,y parameters to allow for mouse pointer 
delay. 



The format of the str parameter is designed so that EMPOWER/CS 
can easily locate the specified pushbutton during script execution in 
Display mode. This format is based on the MS Windows concept of a 
tree structure and may appear similar to the following: 

"Tools|#cl|#c4" 

The MS Windows tree structure is based on a heirarchy of windows 
where each window that is accessed from a primary, or parent, window 
is a child of that parent. The str parameter is listed right to left from 
child to parent window where the right-most item is the name of the 
button. If one of the windows or the button has no name, something like 
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"#cl" will be listed to indicate the window is a certain numbered child of 
the preceding parent window. 

In the example listed above, #c4 was the button activated and is the 
fourth child of the first child (#cl) of the Tools window. 

If a button was activated in the active, or current window, only the 
button will be listed in the str parameter. 

If you wish to edit this function in your script file, you can use the Tree 
Tool under EMPOWER/CS Tools to determine the tree structure for a 
particular pushbutton. 

RETURN VALUE If successful, the ButtonPush( ) function returns 1. If unsuccessful, 
the function will return a zero. 

EXAMPLES In the following example script segment, the user pushed the button 

OK in the current window, "Run", to open an application: 



CurrentWindow ( "Run" ) ; 
Type( "c: \\acct\\c\\acct A M) ; 
ButtonPush("OK\354,153) ; 



AppWait(0.05) ; 

WindowRcv( "CwOX^sCwAcSfCwPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPt'' ) 
WindowRcv( "PtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPt" ) 
WindowRcv { " PtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPt " ) 
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FUNCTION 



Cancel 



SYNTAX 



Cancel (num, opt) 
int num, opt; 



DESCRIPTION 



Parameters 



num 



opt 



An identifier of the logon or cursor structure for which 
operations are to be cancelled 

An option of either all or current 



Comments 

This function may appear throughout your script and is inserted into the 
script when database operations were cancelled for either a logon or 
cursor structure. For example, at some point during the Capture session, 
the user may have requested that the current operation of fetching a 
record was cancelled. 

During script execution, the Cancel { ) function cancels operations in 
progress for the specified structure without closing the structure. The 
opt parameter specifies an option of cancelling all operations or the 
current operation on the specified structure. 

Note: Because this function is inserted into your script based on how 
the client application interacts with the SUT, you should not attempt to 
edit this function or remove it from the script If you change this 
function from when it was captured, you may drastically alter the 
expected behavior of the client and SUT and therefore, break the script 
during execution. 



RETURN VALUE 



If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 



EXAMPLES The following example demonstrates the current option of 

Cancel {). If, during Capture, all desired data has been fetched for a 
query, the user may wish to cancel the query before it has completed 
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Instead, the user may cancel the operation (which saves database 
processing time during script execution). Such an operation would be 
captured into the script as: 

Cancel (CUR1, CURRENT); 

The following example demonstrates using the option all. Suppose a 
logon connection, logi, contained ten cursors. The following function 
would cancel all ten cursors: 

Cancel <L0G1, ALL); 
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FUNCTION Close 

SYNTAX Close { curnum) 

int curnum; 



DESCRIPTION Parameters 

curnum An identifier of the cursor communication structure to be 
closed 



Comments 

A close ( ) function is inserted into the script when a cursor is closed. 
During script execution, closet) closes the cursor communication 
structure that was opened with the associated Open ( ) function. Once a 
cursor is closed, no additional processing (i.e., Parse (), Bind () , 
Define ( ) , Describe { ) , Exec ( ) , etc functions) can be performed on 
that cursor. 

Note: Because this function is inserted into your script based on how 
the client application interacts with the SUT, you should not attempt to 
edit this function or remove it from the script. If you change this 
function from when it was captured, you may drastically alter the 
expected behavior of the client and SUT and therefore, break the script 
during execution. 

RETURN VALUE If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 



EXAMPLES In the following script example, close { ) will close the cursor, curi, 

before the executed script exits: 
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w 

o 
o 



Close (CUR1) ; 
Logoff (L0G1) ; 
Closenv (ORACLED ; 

Endscenario ( "scriptl" ) ; 



SEE ALSO 



Open 
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FUNCTION 



Closenv 



SYNTAX Closenv (dbnum) 

int dbnum; 

DESCRIPTION Parameters 

dbnum A database environment number 

Comments 

closenv () closes the environment opened with the associated 
0penenv(). This function is inserted into the script when a database 
environment is closed 



After a database environment is closed, no logon connections can be 
made within the specified environment 

Note: Because this function is inserted into your script based on how 
the client application interacts with the SUT, you should not attempt to 
edit this function or remove it from the script. If you change this 
function from when it was captured, you may drastically alter the 
expected behavior of the client and SUT and therefore, break the script 
during execution. 

RETURN VALUE If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 



EXAMPLES The following example script segment demonstrates that closenv ( ) 

will close the database environment oraclei before the executed 
script exits: 
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Close (CURD ; 
Logof f (L0G1) ; 
Closenv {ORACLED ; 

Endscenario ( " scriptl " ) ; 



SEE ALSO Openenv 
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FUNCTION 



CmpVar 



SYNTAX 



CmpVar { curnum, var , value ) 



int curnum; 



char *var, value ; 



DESCRIPTION Parameters 

curnum An identifier of a cursor communication structure 



length The length of the variable in bytes 
value The specified value for the comparison 

You may insert the CmpVar ( ) function into your script to compare a 
variable from a SQL statement to a specified value. 

This function determines if the specified variable, var, in the current 
row is equal to the value specified in the value parameter. The address 
of the variable must be passed to CmpVar ( ) . 

This function could be used for fetching records until a desired value is 
returned. 



RETURN VALUE If the variable is equal to the specified value a zero is returned; if the 
variable is greater than the specified value, 1 is returned; and, if the 
variable is less than the specified variable a -1 is returned. 



var 



The variable used for the comparison 



type 



The data type of the variable 
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EXAMPLES 



An example of this function follows: 
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SEE ALSO 



Parse (CUR1, "select ename from employee_table" ) 
Define (CURl. "1", STRING, 50); 
Exec (CURD ; 

Dbset(CURl, FETCHSIZE, 1) ; 

while (CrapVar (CURl, "1", "Smith") != 0) { 

Fetch (CURl) ; 

GetNextRow(CURl) ; 

} 



GetlntVar, GetVar, SetlntVar, SetVar 
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FUNCTION 



Commit 



SYNTAX 



Commit (num) 
int num; 



DESCRIPTION 



Parameters 

num An identifier of a logon or cursor communication structure 



Comments 

The Commit!) function may appear throughout the script and is 
inserted into the script when database processing is committed to the 
database. During script execution, this function commits to the database 
all processing the script has completed(i.e. f updating records, deleting 
records, adding records, etc.) since processing was last commited. The 
parameter num specifies a logon or cursor number for which operations 
are to be committed 

The Rollback () function is inserted into the script if script operations 
are not commited to the database but are rolled back. Rollback!) 
restores the database to its original state before a script was executed. 

Note: Because these functions are inserted into your script based on 
how the client application interacts with the SUT, you should not attempt 
to edit the functions or remove them from the script. If you change 
these function from when they were captured, you may drastically alter 
the expected behavior of the client and SUT and therefore, break the 
script during execution. 



RETURN VALUE 



If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 



EXAMPLES The following example demonstrates that all database processing for 

LOGl will be committed to the database before the executed script 
exits: 
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CommiULOGl) ; 

Close (CURl) ; 
Logof f (LOG1) ; 
Closenv (ORACLEl) ; 



Endscenario ( " scriptl " ) ; 



SEE ALSO Rollback 
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FUNCTION Continue 

SYNTAX Continue ( lognum, transnum) 

int lognum, transnum; 

DESCRIPTION Parameters 

lognum An identifier of a logon communication structure 

transnum An identifier of the transaction to be resumed 
Comments 

The Continue ( ) function specifies an application-defined database 
transaction that is to be continued. This function is captured into the 
script when the client application instructs the database to resume 
execution of the paused transaction. It will be inserted after the 
associated BeginTransaction{ ) and Pause () functions. 

The specified transnum parameter must correspond to a transnum 
specified in an associated Pause () function. A transaction can be 
continued only if no other transactions are currently running on the 
specified logon connection. 

RETURN VALUE If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 



EXAMPLES 



The following example demonstrates this function in a script file: 



BeginTransaction (L0G1) ; 




Pause(LOGl, TRANS 1) ; 




BeginTransaction (L0G1) ; 






(continued on following page . . .) 
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Pause ( LOG1 , TRANS 2 ) ; 

Continue (LOG1, TRANS 1) ; 
Commit (TRANSl) ; 

Continue (TRANS2 ) ; 
Commit (TRANS2) ; 



SEE ALSO 



BeginTransaction, Pause 
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FUNCTION 



CurrentWindow 



SYNTAX 



CurrentWindow (window, left, top, width, height) 



char * window; 

int left, top, width, height; 



DESCRIPTION 



Parameters 
window 



The title of the active window 



left, top 



The left, top x,y coordinates of the window on screen 



width, height The size x,y coordinates of the window on screen 
Comments 

The CurrentWindow ( ) function is captured into your script file to 
record all titled windows that were activated during Capture. This 
function is used to ensure windows are in their captured state during 
script execution in Display mode. It designates a window currently 
active and moves the specified window to its captured position. The 
CurrentWindow ( ) function also is used during Monitor sessions to add 
context to script execution in Display and Non-Display modes. 

The parameter window identifies the title of the current window. The 
top, left and the width, height coordinates indicate the on screen 
coordinates of the specified window. If the width, height coordinates 
are 0,0, the window is in a minimized state. If the top, left x ( y 
coordinates are 0,0 and the width, height coordinates are 
maxwidth, maxheight, the window is maximized. If none of these 
conditions apply, the window is considered to be in a normal state. 

Note: Because this function is inserted into your script based on how 
the client application interacts with the SUT, you should not attempt to 
edit this function or remove it from the script If you change this 
function from when it was captured, you may drastically alter the 
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behavior of the client and SUT and therefore, break the script during 
execution. 



RETURN VALUE (not applicable) 



EXAMPLES In the following example, CurrentWindow ( ) designates that the 

Program Manager window was captured in a normal state: 



AppWait (4.34) ; 

WindowRcv( "SfAcPtSf PtPtSf DwAcSf Sf Sf Pt" ) ; 

CurrentWindow ( "Program Manager" ,413, 679, 1029, 771); 

KeyPress (VK_CONTROL) ; 
KeyPress(VK_F12) ; 

Lef tButtonPress (443,112); 



SEE ALSO InitialWindow 
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FUNCTION 



Data 



SYNTAX 



Data (curnum, str, . ../* args */) 



int curnum; 



char *str, *args; 



DESCRIPTION Parameters 

curnum An identifier of the cursor structure of the associated SQL 
statement 



Comments 

The Data { ) function is inserted into the script when data is specified to 
be input to the database. The str parameter is pipe delimited and lists 
the data for each input variable that was defined with Bind{). 
Therefore, the Data ( ) function will follow a Bind{ ) , BindDef ine ( ) f or 



Bindp ( ) function and also will occur before an Exec ( ) . 

During script execution, Data { ) specifies the data to be inserted into or 
selected from the database. 

The Dbset ( ) option insertsize applies to the Data ( ) function in that 
the number of Data ( ) functions inserted into the script will correspond 
to the value of insertsize. insertsize specifies the number of rows 
of data to be inserted into the database. 

Note: You may edit this function to accept variable arguments in a way 
similar to the C function print f (). The DataO function will accept 
arguments so that data can be passed into the script from the command 
line. Arguments are passed to this function via the script execution 
statement. In the script execution command, arguments follow the 
names of the executable script file and the log file, and all arguments 



str 



The data to be inserted into the database 



arg 



Optional variable arguments 
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must be string pointers. The string conversion specification is provided 
by the characters %s. 

RETURN VALUE If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 



EXAMPLES The following example demontrates a SQL statement and its 

corresponding data line in a script: 





/* insert data into database */ 




Parse(CURl, "insert empno, ename, empjob into emp_table" ) ; 




Bind ( CUR1 , " empno " , INT , 4 ) ; 




Bind ( CUR1 , " ename " , STRING , 3 0); 


■ ~% 


Bind(CURl, "empjob", STRING , 20); 




/* 123 refers to empno, Smith -- ename, typist — empjob */ 




Data(CURl, n 123 | Smith | typist " ) ; 




Exec (CUR1) ; 




The parameter to DataO, "123 | Smith | typist" represents the data 




that was inserted into the database. 12 3 would correspond to empno, 



Smith would correspond to ename, and typist would refer to empjob. 
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The following example demonstrates using this function to accept a variable 
argument: 



Parse (CURl, "select * from emp_table where lname = :name and empjob = :job") ; 

Bind (CURl, ":name\ STRING , 30); 
Bind (CURl, ":job\ STRING , 30); 

/* this Data{) will get name from file and alway use job of typist */ 
Data {CURl, "%s | typist" , Fioreadf ield(dataf ile) ) ; 

Exec (CURl) ; 



EMPOWER/CS-Vl.0.1 



2-47 

Copynghl PERFORMIX, Inc. © 1995 



User's Guide— Reference 



FUNCTION Dberror 

SYNTAX Dberror ( cond) 

int cond; 

DESCRIPTION Parameters 

cond The condition, either continue or exit, for database errors 

Comments 

Similar to the Timeout ( ) function, Dberror ( ) specifies the condition 
or action to be taken when a script encounters a database error. Valid 
conditions are continue and exit where the script will either continue 
script execution or exit the script when a database error is encountered. 

The default function Dberror (continue) is placed at the top of every 
script created by EMPOWER/CS. During script execution, 
Dberror (continue) specifies that the script will continue if it 
enounters a database error. You may edit this function and/or insert 
multiple Dberror () functions in the script file to suit your testing 
needs. 

RETURN VALUE (not applicable) 

EXAMPLES The following example demonstrates the Dberror ( ) function set to 

continue: 
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/* EMPOWER/CS VI. 0.1 Remote Terminal Emulator Script */ 

Typerate(5); /* Typing delay in CPS */ 

Thinkuni form (1,2.5) ; /* Think delay */ 

Seed(getpid{) } ; /* Seed random number generator */ 

Timeout (3 00, CONTINUE); /* What to do if function takes too long */ 

Dberror (CONTINUE) ; /* What to do on Database errors */ 

Unset (NOTIFY) ; /* Don't display warnings. I'll use Mon to find them */ 



Timeout 
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FUNCTION 



Dbset 



SYNTAX 



Dbset (num, opt y value) 
int num, opt, value; 



DESCRIPTION 



Parameters 



num 



Specifies an environment, logon structure, or cursor for 
which options are being set 



opt 



Specifies the option being set 



value Sets a value for the option, either a numerical or string value, 

Or TRUE Or FALSE 

Comments 

The Dbset { ) function is used in a script to set certain features for a 
particular database environment, logon structure, or cursor. These 
features will apply to all subsequent operations in the specified 
structure. Dbset ( ) is inserted into your script according to the behavior 
of your client application and the SUT. The options set in this function 
are dependent on the client application. Because these options are not 
user-defined, but occur specific to the database and client application, 
the Dbset () function generally should not be edited or removed from 
your script file. 

The Dbset () options that commonly will appear in your scripts are 
listed below; 

FETCHSIZE 

Specifies the number of records to fetch from the database when a Fetch () 
function is executed. This number will be less than or equal to the value 
specified in the maxarrsize. The Dbset ( ) function that sets the fetchsize will 
occur before a Fetch{). The fetchsize value can not be larger than the 
maxarrsize. If the fetchsize was specified as 50 and maxarrsize was 
specified as 20, EMPOWER/CS will reduce the fetchsize to 20. 
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MAXARRSIZE 

Sets the maximum array size for retrieving or inserting records. If the array size 
is set at 20, 20 rows of data can be inserted or fetched. This option set at 20 
allocates 20 placeholders for inserting or fetching 20 rows of data The Dbset { ) 
function that sets the maxarrsize will occur before a the Bind ( ) and Define ( ) 
functions in a script 

INSERTSIZE 

Specifies the number of rows of data to be inserted into the database. This 
option will be listed before the DataO function in a script in the format 
Dbset (CUR1 , insertsize , n) . This option allows array binding. For example, if 
n is 0 or 1, one row can be inserted at a time into the database. If n is 50, 50 
rows will be inserted into the database and 50 data lines will be listed for every 
yj row before Exec { ) . The insertsize value can not be larger than the specified 

~J MAXARRSIZE. 

yi OFFSET 

-JO Specifies the offset for inserting records in an array. This option is used with 

^" the insertsize option. If an array includes four names and the offset is set to 

2, then inserting rows will start from the second position with the second name. 

Q The Dbset ( ) function specifying this option will occur before an Exec ( ) 

1M function. If the offset is specified as larger than the maxarrsize, a database 

^ error will occur. 

WAITRES 

Specifies whether or not to wait for resources. If this option is set to true, the 
script will wait indefinitely for requested information from the database. If it is 
set to false and the script does not receive the requested information, the 
script will receive an error that the resource was not available. Script execution 
will then either continue or exit based on the condition set in Dberror { ) , 

DEFER 

Specifies whether or not to defer the Parse ( ) statement. If this option is set to 
true, a deferred parse will be performed when the script encounters the 
Parse ( ) function. If the option is set to false, a normal Parse ( ) is executed. 
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Normally, the SQL statement is sent to the database when the script encounters 
Parse () and is processed to ensure it is semantically correct. The SQL 
statement is stored waiting for the Exec { ) call that actually will execute it. If 
defer is set to true, the SQL statement is not sent to the database until the 
script encounters an operation that requires input from the database such as 
Exec ( ) or DescribeO. 

Other DbsetO options may appear in your scripts. A full list of all 
possible options follows. This list is divided into those options that set 
integer values and those that require TRUE or FALSE values: 

Description 

number of rows to be fetched 
max number of rows to be fetched 
number of rows to be inserted 
row number where to start inserting 
maximum number of connections in an environment 
maximum packetsize on log 
maximum number of rows to return 
limits size of text or image data 
transaction isolation level 
turns specified authorization off 
turns specified authorization on 
security label spec, cur read level 
security label spec, cur write lev 
which day of week is first 
format of date 

disable inserts into table ident column 
enable inserts into table ident column 



Integer Value 
Option 
FETCHSIZE 
MAXARRSIZE 
INSERTSIZE 
OFFSET 
MAXCONNECT 
PACKETSIZE 
ROWCOUNT 
TEXTSIZE 
ISOLATIONLEVEL 
AUTHOFF 
AUTHON 
CURREAD 
CURWRITE 
DATEFIRST 
DATEFORMAT 
IDENT ITYOFF 
IDEWTITYON 



TRUE or FALSE 

Option Description 

defer deferred parse 

update cursor is for updating 

readonly cursor is read only 

saveopts do not deallocate the structure 

forcelogoff force logoff 
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FORCEEXIT 


force exit 


RECOMPILE 


recompile stored procedure before executing 


RETPARAM 


return parameter 


TRUNCATE 


truncate data 


INTERRUPT 


application can be interrupted 


ANSI„BINDS 


force ansi style binds 


DEFER_IO 


deferred io 


ASYNC_I0 


async io 


SYNC_IO 


sync io 


EXTRA_INF 


return extra information for error 


EXPOSE_FMTS 


expose formats 


BULKCOPY 


allow bulk copy on connection 


ASYNCNOTIFICATION 


asynchronous notification 


DIAGJTIMEOUT 


what to do on a timeout 


APPSECURITY 


application-defined security 


SYB SECURITY 


sybase-defined security 


ENCSECURITY 


encrtyped security 


TRUSTSECURITY 


trusted security 


ANSINULL 


ansi style nulls 


ANSI PERM 


ansi style permissions 


ARITHABORT 


what to do on arithmetic errors 


ARITHIGNORE 


what to do on arithmetic div. by 0 


CURCLOSETRAN 


close all cursors on end transaction 


NONSTANDSQL 


flag non standard sql 


FORCEPLAN 


force plan or not 


FORMATONLY 


only send format for data 


GETDATA 


returns information on every sql statement 


NOROWCOUNT 


row count 


PARSEONLY 


only check syntax, do not execute 


QUOTEDIDEOT 


all double quotes signify identifiers 


PARSETREES 


returns parse resolution trees 


SHOWPLAN 


generates a description of procedure plan 


IOSTATS 


return internal io statistics 


TIMESTATS 


return time statistics 


IGNORETRUNC 


ignore truncation errors 


AUTOCOMMIT 


commit on every Exec() 


WAITRES 


wait for resources instead of error 


SPECIAL 


Sybase version of cursor 


H I DDEN_KEY S 


expose hidden keys 



EMPOWER/CS-Vl.0.1 



2-53 

Copyright PERFORMIX, Inc. 0 1995 



User's Guide— Reference 



RETURN VALUE If the function is successful, zero is returned If an error occurs, -1 is 
returned. 

EXAMPLES In the following example, the client application specified that the 

defer option be set to true so that a deferred Parse ( ) will occur: 



Dbset (CURl , DEFER, TRUE) ; 

Parse (CURl, H SELECT ID, FIRST_NAME, LAST_NAME, ADDRESS_LINE_1 , 

ADDRES S_L INE_2 , ADDRESS_LINE_3 , PHONE_NUMBER, FAX_NUMBER, COMM_PAID_YTD, 

ACCOUNT_BALANCE r COMMENTS FROM CUSTOMERS M ) ; 



In this next example, the maxarrsize is set to a size 64 array for the 
subsequent script operations: 



Dbset (CURl, MAXARRSIZE, 64) ; 


Define (CURl, 


" 1 " , 


STRING, 40); 


Define (CURl, 


,l 2", 


CHAR, 21) ( 




Define (CURl , 


"3", 


CHAR, 21), 




Define (CURl, 


"4", 


CHAR, 21), 




Define (CURl, 


" 5 " , 


CHAR, 21), 




Define (CURl, 


" 6 " , 


CHAR, 21) 




Define (CURl, 


"7", 


CHAR, 16) 




Define (CURl, 


" 8 " , 


CHAR, 16) 




Define (CURl, 


" 9 " , 


STRING, 40); 


Define (CURl, 


"10" 


, STRING, 40); 


Define (CURl, 


"11" 


, CHAR, 241); 


Exec (CURl) ; 
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FUNCTION 



Define 



SYNTAX 



Def ine (curnum, pos, type, length) 

int curnum; 

char *pos ; 

int type, length; 



DESCRIPTION Parameters 

curnum An identifier of the cursor of the associated SQL statement 



length The length in bytes of the variable being defined 
Comments 

The Define ( ) function is inserted into the script during a query when 
output variables are defined for storing data fetched from the database. 
During script execution, Define () defines output variables for each 
select-list item listed in a SQL query statement. The SUT places the 
requested data in these output variables when a Fetch () function is 
later called 

The Define () function associates an output variable with each select- 
list item in a SQL query statement Each select-list item is designated in 
the parameters to Def ine { ) by a cursor number, the items position in 
the SQL statement, the variables data type, and the variable's length. 
The positions defined in the pos parameter begin with 1 for the first (or 
left-most) select-list item, 2 for the second, etc. 

The Define ( ) function is called after a Parse ( ) statement and before 
Fetch(). 

Note: Because this function is inserted into your script based on how 
the client application interacts with the SUT, you should not attempt to 



pos 



The position of the select-list item in the SQL statement 



type 



The variable's data type 
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edit this function or remove it from the script, [f you change this 
function from when it was captured, you may drastically alter the 
expected behavior of the client and SUT and therefore, break the script 
during execution. 

RETURN VALUE If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 

EXAMPLES In the following script segment, the Define ( ) functions define 

variables for each select-list item of the Parse {) statement. Notice in 
the first Define ( ) statement below, the variable "l" refers to empno 
in the SQL statement 



Parse (CUR1, 


"SELECT EMPNO, ENAME, 


JOB, MGR, 


HIREDATE, 


SAL, 


COMM, DEPTNO 


FROM EMP, UPDATE 


OF EMPNO, ENAME, 


JOB, MGR, 


HIREDATE , 


SAL, 


COMM, 


DEPTNO") ; 














Def ine{CURl, 




CHAR, 5); 


/* posl = 


EMPNO */ 






Define (CUR1, 


■2', 


STRING, 11); 


/* pos2 = 


ENAME */ 






Define (CUR1, 


■3", 


STRING, 10); 


/* pos3 = 


JOB */ 






Define (CUR1, 


■4', 


STRING, 5); 


/* pos4 = 


MGR */ 






Define (CUR1, 


"5", 


STRING, 10); 


/* pos5 = 


HIREDATE 


V 




Define (CUR1, 


"6\ 


LONG, 4); 


/* pos6 = 


SAL */ 






Def ine{CURl, 


"7", 


STRING, 9); 


/* pos7 = 


COMM */ 






Define (CURl, 


"8\ 


INT, 4); 


/* pos8 = 


DEPTNO */ 






Exec(CURl) ; 















SEE ALSO Bind, Bindp, BindDefine 
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FUNCTION Describe 

SYNTAX Describe (curnum, pos) 

int curnum, pos; 



DESCRIPTION Parameters 

curnum An identifier of the cursor structure of the associated SQL 
statement 



pos 



The position of the variable in the SQL statement 



Comments 

During Capture, if a client application requests from the SUT a 
description of a variable in the SQL statement, a Describe () function 
is inserted into the script The Describe () function is used only for 
database queries. 

During script execution, the Describe () function sends a request to 
the SUT for a description of a specified variable. This variable is 
specified by a cursor number and by the variable's position in the 
associated SQL statement Information returned about a variable may 
include the name of the variable, the variable's data type, the length of 
the variable, whether the data in the variable is null-terminated or 
updateable, etc. This information is used for converting, displaying, or 
storing the data that will be returned for a query. 



Note: Because this function is inserted into your script based on how 
the client application interacts with the SUT, you should not attempt to 
edit this function or remove it from the script. If you change this 
function from when it was captured, you may drastically alter the 
expected behavior of the client and SUT and therefore, break the script 
during execution. 



RETURN VALUE If the function is successful, zero is returned. If an error occurs, T is 
returned. 
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EXAMPLES The following example demonstrates how Describe ( ) would appear 

in a script: 



Parse (CURl, " select ename from emp_table " ) ; 
Describe (CURl , 1); /* describes ename */ 



The following is an example of the output for Describe () which is 
recorded in the script's log file: 



»> Describe (CURl , 1 ) ; 

size=20, type=CHAR, name = ename, namelen=10 , dsize=0, prec=0 / 
scale=0 , nullok=0 



SEE ALSO DescribeAH, DescribeProc 
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FUNCTION 



DescribeAll 



SYNTAX 



DescribeAll (curnum, posl, pos2) 
int curnum, posl, pos2; 



DESCRIPTION Parameters 

curnum An identifier of a cursor structure of the associated SQL 
statement 

posl The starting position in the SQL statement for a Describe 
operation 

pos2 The ending position in the SQL statement for a Describe 
operation 

Comments 

A DescribeAll ( } function is inserted into the script when a 
Describe () operation was performed for each select-list item specified 
between two positions of the SQL statement. This function describes 
each select list item, or variable, starting from the position specified in 
posl to the position specified in pos2. 

Note: Because this function is inserted into your script based on how 
the client application interacts with the SUT, you should not attempt to 
edit this function or remove it from the script. If you change this 
function from when it was captured in the script file, you may drastically 
alter the behavior of the application and SUT and therefore, break your 
script during execution. 

RETURN VALUE If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 

EXAMPLES In the following example, the variables listed in the SQL statement 

from curi, starting from the first position to the twelfth position, 
which will be described: 
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Parse(CURl, " SELECT ID, FIRST_NAME, LAST_NAME, ADDRESS_LINE_1 , 
ADDRESS_LINE_2 , ADDRESS_LINE_3 , PHONE_NUMBER, FAX_NUMBER, COMM_PAID_YTD , 
ACCOUNT_BALANCE, COMMENTS FROM CUSTOMERS "); 

DescribeAlKCURl, 1, 12); 



SEE ALSO Describe, DescribeProc 
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FUNCTION 



DescribeProc 



SYNTAX 



DescribeProc { lognum, procname) 
int lognum; 
char *procname; 



DESCRIPTION Parameters 

lognum An identifier of a logon communication structure 

procname The name of the procedure being described 
Comments 

This function is inserted into the script during Capture when the client 
application sends a request to the database for a description of a 
procedure. DescribeProc ( ) performs a Describe () operation on all 
the variables referred to in a specified procedure returning information 
about the variables used in that procedure. 

A logon structure is specified in the parameter instead of cursor 
because the stored procedure must be described before a parse is 
completed Therefore, the DescribeProc ( ) function will be listed in 
the script before the Open() and Parse () functions. A stored 
procedure is an operation that is stored on the database to be executed 
later. 

Note: Because this function is inserted into your script based on how 
the client application interacts with the SUT, you should not attempt to 
edit this function or remove it from the script. If you change this 
function from when it was captured, you may drastically alter the 
behavior of the client and SUT and, therefore, break the script during 
execution. 

RETURN VALUE If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 



SEE ALSO 



Describe, DescribeAII 
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FUNCTION Difftime 

SYNTAX double Dif f time<first, second, diff); 

struct timevalue *first, *second, *diff; 

DESCRIPTION Parameters 

first The first time stamp value 

second The second time stamp value 

diff Variable that stores the difference between first and 
second 

Comments 

You may insert this function into your script when editing. It is used to 
ensure that certain activities in a script occur in a specified amount of 
time. 

Difftime () computes the difference in seconds between the first 
and second values and stores the result in the variable diff. The time 
difference is returned in a double value. This allows a time difference to 
be expressed as a floating point (fractional) number, as in 1.5 (one and a 
half seconds). Normally, the first value is earlier than the second. 



The first, second, and diff values are time stamps of struct 
timevalue type. The variable struct timevalue is defined in 
$EMPOWER/h/empower .h as: 



struct timevalue 


{ 






long sec; 


/* 


seconds since Jan 1. 


1970 */ 


short hsec; 

} 


/* 


and hundredths of a 


second */ 



RETURN VALUE The return value is positive if the first time value is earlier than the 
second time value. Otherwise,. the return value is negative. 
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EXAMPLES This example script segment measures the time it takes to enter 

information into a field and press the left mouse button. One of the past 
uses of the Dif f time { ) function was to help pace a script to provide a 
required transaction throughput. This operation now is accomplished 
with Empowers Pace functions. 



char buf [10] ; 
double difftm; 

struct timevalue timel, time2; 



Time (&timel) ; 
Type< "1234~M" ) ; 

LeftButtonPress (282, 174) ; 



AppWait (0.05) ; 
WindowRcvpSfSfSfSf " ) ; 
Time (&time2 ) ; 

dif ftm=Diff time (fctimel, &time2, 0) ; 
sprintftbuf, "time is %.2f" , difftm); 
Log (buf) ; 



SEE ALSO Time, Eventtime, Paceconstant, Pacetne, Paceunifonn 
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FUNCTION 



Endfunction 



SYNTAX 



Endfunction (str } 
char *str; 



DESCRIPTION Parameters 

str The name of the function. This parameter is a null- 

terminated string. 



Comments 

Endfunction { ) is used to mark the end of a function. This function is 
inserted into the script automatically during Capture when you specify 
the end of a function or, it can be inserted when editing your script 

Endf unction ( ) works with and must have a corresponding 
Beginf unction ( ) to define a task you wish to measure. The 
Endfunction () statement and its corresponding Beginf unction ( ) 
must use the same function name, i.e. str parameter. 

Endfunction ( ) records the name of the function and the time at which 
the event occurred in the log file. 



RETURN VALUE (not applicable) 



EXAMPLES In the following example, the Beginf unction ( ) and Endf unction ( ) 

statements are placed in a C language function that consists of opening 
a window. The name of the function is openwindow. A function call is 
placed within the scenario and the actual function is listed after 
Endscenario ( ) : 
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Empower { ) ; 
{ 

AppWait(0.33) ; 
WindowRcv ( " Sf Sf Sf Pt " ) ; 



openwindow ( ) ; 

LeftButtonDown(132, 91} ; 
LeftButtonUp(158,212) ; 



AppWait(3.52) ; 
WindowRcv{ "ScSfSfSfPt" ) ; 

Endscenario ( "example" ) ; 
} 

openwindow ( ) 
( 

Beginsource { ■ example" ) ; 
Begin funct ion { "openwindow" ) ; 

LeftDblPress(438,304) ; 
LeftDblClick(438,304>; 

AppWait(0.24) ; 

WindowRcv { "PtCoCwCwDwAcSfC^oSfO^^ ) ; 

WindowRcv { " Pt " ) ; 

CurrentWindow ( "New. ..**); 

/* Clicked {Button) (Cancel) */ 
LeftButtonDown(342 / 256) ; 

Endfunction ( •openwindow" ) ; 

Endsource { ) ; 

} 
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Execution of Endfunction( "queryl" ) could cause the following time 
stamp to be recorded in the script's log file. 

»> 26 Endfunction( "queryl" ) 04:11:23.29 

SEE ALSO Beginfunction 
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FUNCTION Endscenario 

SYNTAX Endscenario (str) 

char *str; 



DESCRIPTION Parameters 

str The name of the script as defined in the Capture session. 

This name is a null-terminated character string. 

Comments 

This function is inserted automatically into your script file during 
Capture to define the end of a scenario. Endscenario ( } works with 
and must have a corresponding Beginscenario ( ) to define a scenario. 
The Endscenario { ) function and its corresponding Beginscenario ( ) 
must use the same scenario name, i.e., str parameter. 

Endscenario ( ) will record in the log file the name of the scenario and 
the time at which the event occurred. 



EMPOWER/CS provides summary performance information for each 
scenario. For example, the Report tool provides scenario start and stop 
times, duration, throughput, and average response times. 

By default, the duration of the test is determined by the time stamps of 
the first Beginscenario ( ) and of the last Endscenario ( ) . 



RETURN VALUE (not applicable) 



EXAMPLES The name of the scenario is taken from the name of the script source 

file. Initiation of capturing the script example would cause the following 
functions to be inserted at the beginning and end of the script 



Beginscenario ( "example" ) 
Endscenario ( M example " ) 
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The log file created from script execution will contain time stamps for 
the beginning and end of the scenario. 

Example: 

>>> 10 Beginscenario (" example" ) 12:05:29.00 
»> 462 Endscenario( "example" ) 12:08:23.07 



SEE ALSO Beginscenario 
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FUNCTION Endsource 

SYNTAX Endsource ( ) ; 

DESCRIPTION If a script is compiled with multiple object files, each object file's 

source script should include BeginsourceO and Endsource ( ) 
statements which are used to specify a source file. The Beginsource ( ) 
function's parameter is a character string naming the source file; 
Endsource ( ) has no parameters. 

You should insert the Beginsource ( ) function during script editing at 
the source file's entry point, typically just before the first executable 
statement in each function. The Endsource ( ) function should be placed 

55 at the source file's exit point, typically just after the last executable 

fp statement in each function. 

!f RETURN VALUE (not applicable) 

=p EXAMPLES In the following example, elements of a function called logof f 1 ( ) 

f may be contained in a separate script file called exitapp.c, as shown: 



logofflO 
{ 

Beginsource ( "exitapp" ) ; 
Beginf unction { " logof f 1 " ) ; 

Think(9.05) ; 

Lef tButtonDown(207, 97) ; 
LeftButtonUp(226,241) ; 



AppWait (0.33) ; 
WindowRcv ( " ScDwAc " ) ; 



(continued on following page . . .) 
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CurrentWindow( "Capture - scriptl " , 21 , 690 , 57 , 726 ) ; 
Commit (LOG1) ; 



Close {CURD ; 
Logoff (LOG1) ; 
Closenv (ORACLE) ; 

Endf unction { "logoff 1" ) ; 

Endsource ( ) ; 

} 



SEE ALSO Beginsource 
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FUNCTION 



Endtimer 



SYNTAX 



Endtimer ( str ) 



char *str; 



DESCRIPTION 



Parameters 



str 



A string that specifies the name of the timer to end 



Comments 

Endtimer {) is used in a script for measuring specific script activity. 
These functions are time stamped in the executed script's log file and 
are used by Report for measuring response time of the specified 
activity. Endtimer ( ) must be called after its corresponding 
Begintimer ( ) function and the corresponding functions must have the 
same str parameter. 

The Begintimer ( ) and Endtimer ( ) functions can be nested 

If the Capture option Insert timer is selected, the Begintimer ( ) and 
Endtimer () functions are inserted automatically into the script by 
EMPOWER/CS to measure response time of database traffic. These 
functions are inserted around database traffic that occurs between two 
user events. A user event such as pressing the Return key on the 
keyboard or activating a pushbutton on screen may initiate database 
activity. The str parameter identifies the user event that initiated the 
database activity. For example, if activating a pushbutton initiated 
database activity, the parameter to the associated Begintimer () and 
Endtimer { ) functions would list a two-level tree structure that lists the 
parent window and the button. 

The Endtimer ( ) function will occur at the end of the database activity 
when a window is drawn on screen or another set of user input begins. 

These functions also can be user-specified. Similar to the functions 
BeginfunctionO and Endf unction () , they can be inserted manually 
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into the script when editing or by activating the EMPOWER/CS Timer 
button in the Capture window during Capture. If you select the Timer 
button, Begintimer { } is inserted into the script measuring activity until 
the End button is selected to insert Endtimer ( ) . 

When editing your script, you may change the str parameter to a string 
that is more meaningful for your emulation. 

RETURN VALUE (not applicable) 

In the following example, Begintimer ( ) and Endtimer { ) were 
inserted into the script around database activity. Notice that the 
parameter to these functions lists the last user event, which was 
pressing the OK button in the window titled Status. 



CurrentWindowf "Status" ,240, 180,408,301) ; 
ButtonPush { "OK" , 322 ,267) ; 

WindowRcv ( "Sf AcSf Dw" ) ; 



Begintimer { " Status_OK" ) ; 

Close (CUR1) ; 
Logoff (LOG1) ; 
Closenv (ORACLE) ; 

Endtimer ( "Status_OK" ) ; 



SEE ALSO Begintimer 



EXAMPLES 



f 5 ^ 
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FUNCTION 



Eventtime 



SYNTAX 



int Eventtime {event , p) 
int event; 

struct timevalue *p; 



DESCRIPTION Parameters 

event The name of an EMPOWER/CS event 

p A timevalue structure where the returned event time is 

stored 

Comments 

You can insert this function when editing your script file. Eventtime ( ) 
retrieves the time at which the last of several events occurred. Valid 
events defined in $ EMPOWER/ h/ empower .h are: 



EVENT 

TSTART 

TBF 

TEF 

TBS 

TES 

TBT 

TET 



DESCRIPTION 
time that script starts 
time at last beginfunction 
time at last endfunction 
time at last beginscenario 
time at last endscenario 
time at last begintimer 
time at last endtimer 



The returned event time is stored in a timevalue structure pointed to by 
p. The struct timevalue is defined in $EMPOWER/h/empowercs .h as: 



struct timevalue { 
long sec; 
short hsec; 

} 



/*seconds since Jan. 1 1970*/ 
/*hundredths of a second*/ 
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RETURN VALUE Eventtime { ) returns 0 if successful and returns -1 if the event is 
undefined. 

EXAMPLES* This example script segment uses Eventtime ( ) and Dif f time ( ) to 

record the duration of events in the log file. Before the EMPOWER 
Pace functions were developed, these functions helped the user to 
maintain a constant transaction throughput (Some script content is left 
out for brevity.) 



char buf [30] ; 
double difftm; 

struct timevalue timel, time2, time3, time4; 




Beginscenario ( " scriptl " ) ; 




Beginf unction ( " logoutl " ) ; 




Endf unction { "logoutl" ) ; 




Endscenario { " scriptl M ) ; 




Eventtime (TBF, &timel) ; 
Eventtime (TEF, &time2) ; 
Eventtime (TBS, &time3) ; 
Eventtime (TES , &time4) ; 




dif ftm=Diff time (5ctimel,&time2, 0) ; 

sprint f (buf, "logoutl function was %.2f seconds", 

Log (buf) ; 


difftm) ; 


dif ftm=Diff time (&time3 , &time4 , 0 ) ; 

sprint f (buf y "scenario duration was %.2f seconds" 
Log (buf) ; 


, difftm) ; 
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The relevant portion of the script's log file follows: 



>>> 


20 


Beginscenario ( "scriptl " ) 14:10:44.26 


>>> 


368 


Beginf unction ( " logout 1 " ) 14:11:48.20 


>>> 


390 


Endf unction ( n logoutl " ) 14:11:54. 37 


>>> 


352 


Endscenario ( 11 scriptl " ) 14:11:54.37 


>>> 


359 


Log ("logoutl function was 6.17 seconds") 


>>> 


362 


Log (" scenario duration was 70.11 seconds") 



SEE ALSO Difftime, Paceconstant, Pacetne, Paceuniform, Time 
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FUNCTION 



Exec 



SYNTAX 



Exec (curnum) 



int curnum; 



DESCRIPTION Parameters 

curnum An identifier of the cursor communication structure 
specified in the associated Parse ( ) 



Comments 

This function is inserted into the script when the Parse ( ) statement is 
executed on the SUT. During script execution, Exec ( ) instructs the 
SUT to execute the current Parse ( ) statement Exec ( ) also forces all 
data and other relevant information to be passed from the client to the 
SUT. 

Exec { ) is called after a Parse ( ) and all the Bind ( ) or Define ( ) 
statements associated with a specific cursor. For database queries, the 
requested rows are fetched with the Fetch { ) function after Exec ( ) has 
been called. 

Note: Because this function is inserted into your script based on how 
the client application interacts with the SUT, you should not attempt to 
edit this function or remove it from the script If you change this 
function from when it was captured, you may drastically alter the 
expected behavior of the application and SUT and therefore, break the 
script during execution. 



RETURN VALUE If the function is successful, zero is returned. If an error occurs, T is 
returned. 



EXAMPLES 



In the following script segment the Exec { ) statement is called for the 
cursor, CUR1: 
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Open (L0G1, CURl) ; 

Parse (CURD "SELECT EMPNO, ENAME, JOB, MGR, HIREDATE , 
SAL, COMM, DEPTNO FROM EMP, UPDATE OF EMPNO , ENAME, 
JOB, MGR, HIREDATE, SAL, COMM, DEPTNO"); 



Define (CURl, 


" 1 " , 


STRING, 


5) ; 


Define (CURl, 


M 2 " , 


STRING, 


11); 


Define (CURl, 


" 3 " , 


STRING, 


10) ; 


Define (CURl, 


"4", 


STRING, 


5) ; 


Define (CURl, 




STRING, 


10) ; 


Define (CURl, 


" 6 " , 


STRING, 


9) ; 


Define (CURl, 


"7", 


STRING, 


9) ; 


Define (CURl, 


" 8 " , 


STRING, 


3) ; 


Exec (CURl) ; 









Fetch (CURl ) ; 



SEE ALSO Parse, Fetch 
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FUNCTION Fetch 

SYNTAX Fetch (curnum) 

int curnum; 

DESCRIPTION Parameters 

cumum An identifier of the cursor communication structure 
specified in the associated Parse { ) 

Comments 

This function is inserted into the script when the requested data in the 
associated Parse { ) , or SQL, statement is retrieved from the database. 
During script execution, Fetch ( ) retrieves the data that satisfies the 
query. This data is retrieved from the database into a buffer on the 
01 UNIX script driver. 

~ The number of rows of data to be fetched is specified in the 

jg fetchsize option of the Dbset { ) function in the following format 

f Dbset (curnum, FETCHSIZE, n) 

ft] The parameter n in this Dbset ( ) function specifies the number of rows 

yl of data to be fetched with 1 as the default of n. 

^ Each Fetch { ) statement returns the set of rows from the database that 

satisfies a query. After the last row has been returned, the next fetch 
will return an error that no remaining rows could be fetched. The 
GetNextRowO function is used to retrieve individual rows from the 
buffer on the UNIX script driver. 

The Fetch {) statement is called after the Parse {) and Exec ( ) 
functions. 

Note: Because this function is inserted into your script based on how 
the client application interacts with the SUT, you should not attempt to 
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edit this function or remove it from the script. If you change this 
function from when it was captured, you may drastically alter the 
expected behavior of the application and SUT and therefore, break the 
script during execution. 

RETURN VALUE Fetch ( ) returns the number of rows fetched from the database. If no 
more rows can be fetched, an error will be returned. 

EXAMPLES In the following example, the fetchsize for the cursor, CUR1, is set to 

4 in the Dbset { ) function: 

Dbset(CURl, FETCHSIZE 4) 



In the following script segment, Fetch ( ) is called for the cursor, curI: 





Parse (CURI , 


" SELECT ID, FIRST.NAME, LAST_NAME, ADDRES S_LINE_1 , 




ADDRES S_L INE_2 , ADDRES S_L INE_3 , PHONE_NUMBER , FAX_NUMBER , COMM_PAID_YTD , 




ACCOUNT_BALANCE , 


COMMENTS FROM CUSTOMERS " ) ; 




DescribeAll (CURI, 


1, 12); 






Dbset (CUR1,MAXARRSIZE, 64) , 






Define (CURI, 


"l". 


STRING, 40); 




Define (CURI, 


"2\ 


CHAR, 21), 






Define (CURI, 


'3-, 


CHAR, 21), 






Define (CURI, 


-4", 


CHAR, 21), 






Define (CURI, 


"5", 


CHAR, 21}, 






Define (CURI, 


"6", 


CHAR, 21) 






Define (CURI, 


"7", 


CHAR, 16) 






Define (CURI, 


"8", 


CHAR, 16) 






Define (CURI, 


"9", 


STRING, 40); 




Define (CURI, 


•10" 


, STRING, 40) ; 




Define (CURI, 


-11 ■ 


, CHAR, 241); 




Exec (CURD ; 










Dbset (CURI, 


FETCHSIZE, 64); 






Fetch (CURI) ; 









EMPOWER/CS-Vl.0.1 



2-79 

Copyright PERFORMIX, Inc. © 1995 



User's Guide— Reference 



SEE ALSO Dbset, FetchRaw, GetNextRow, Parse 



o 

m 
si 

= 

o 
ry 
m 
o 

a 



EMPOWER/CS-Vl.0.1 



2-80 

Copyright PERFORMIX, Inc. © 1995 



User's Guide— Reference 



FUNCTION 



FetchRaw 



SYNTAX 



FetchRaw (curnum, pos, type, length) 
int curnum, pos, type, length; 



DESCRIPTION Parameters 

curnum An identifier of a cursor communication structure of the 
associated Parse {) 

pos The position of the specified variable in the SQL- statement 

type The variable's data type 

length The number of bytes of data to retrieve from the SUT 
Comments 

The FetchRaw {) function is inserted into the script instead of a 
Fetch () if the specified data to be retrieved is in binary form. This 
data is fetched in length-sized portions from the SUT. 

The parameters to FetchRaw {) specify the cursor number of the 
associated SQL statement, the position of the associated select-list item 
in the SQL statement, the data type of the output variable, and the 
number of bytes of data to retrieve from the database. 



Note: Because this function is inserted into your script based on how 
the client application interacts with the SUT, you should not attempt to 
edit this function or remove it from the script. If you change this 
function from when it was captured in the script file, you may drastically 
alter the expected behavior of the application and SUT and therefore, 
break your script during execution. 



RETURN VALUE FetchRaw ( ) returns the number of rows fetched from the database. If 
no more rows can be fetched, an error will be returned. 
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EXAMPLES The following example demonstrates a FetchRaw() function that 

fetches binary data in 1024 byte sections until no more data can be 
fetched: 



long n; 
do { 

n=FetchRaw (CUR1 , 1 , BINARY, 1024 ) ; 
} while (n>0) ' 



SEE ALSO Fetch 
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File Input/ Output Functions 

You can insert EMPOWER/CS File Input/Output functions into your script when 
editing. These functions are used to read and write files. Such capabilities are 
useful for load, tests requiring interaction with data files on the UNIX driver 
machine and for simplifying complex scripts such as database entry scripts. 

The EMPOWER/CS file input/output functions are used in your scripts to read 
data from a file, send data from the file to the SUT, receive data from the SUT, and 
write those data to a file. These functions simplify the C language statements that 
would need to be added to scripts to accomplish the same thing. 

The environment variable e_fiopath can be used to specify the directory in 
which the files to be accessed reside. A file must be opened before it can be 
accessed with the file input/output functions. If a file contains NULL characters, an 
error will occur when the file is read by an input/output function. 

Three global variables are used for file input/output. They are defined 
automatically as follows: 



unsigned char *FI0BUFFER 

int FIOLEN 

int FIOBUFFERSZ 



The variable fiobuffer is a pointer to the characters read from the file. This 
variable often is used when sending data read from a file to the SUT. The variable 
fiolen is the number of valid characters in fiobuffer. If the value of fiolen is 
less than or equal to zero, then either an error occurred or the end-of-file (EOF) was 
reached. The variable fiobuffersz is the maximum size of the data that can be 
read at one time. The default value of fiobuffersz is 512 characters. If the value 
of fiobuffersz is redefined in a script, it must be redefined before any file 
input/ output functions that reference the file are encountered. 

These functions are described in the following reference entries. 
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FUNCTION 



Fioautorewind 



SYNTAX 



Fioautorewind (filename) 
char * filename; 



DESCRIPTION Parameters 

filename The file used for the operation 

Comments 

The Fioautorewind! ) function automatically rewinds the file pointer 
to the beginning of the file specified in filename whenever an end-of- 
file is encountered If the end-of-file is not encountered, scripts will 
bypass this function. Fioautorewind { ) is useful if multiple scripts read 
data from one file. 



RETURN VALUE 



If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 



EXAMPLES The following examples show you how to use the rewind functions to 

re-use data in an input file. Notice that Fioautorewind ( ) saves you 
some programming time because you do not have determine if you are 
at the end of the file: 



Fioautorewind ( " info " ) ; 
Fioreadline ( " info" ) ; 
Type ( M %s " , FIOBUFFER) ; 



OR 
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Fioreadline ( " info " ) ; 
if <FI0LEN==-1) { 
Fiorewindt " info" ) ; 
Fioreadline ( "info" ) ; 
} 

Type{"%s" , FIOBUFFER); 



SEE ALSO 



Fiorewind 
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FUNCTION Fio close 

SYNTAX Fioclosetfilen ame ) 

char * filename; 

DESCRIPTION Parameters 

filename - The file to close 

Comments 

See the description under File Input/Output Functions for a general 
explanation of these functions. 

The FiocloseO function closes the file in the parameter filename. 
Open files automatically are closed when the script exits. However, for 
good programming practice, using this function in your script file may 
be useful. 

RETURN VALUE If the function is successful, zero is returned If an error occurs, -1 is 
returned. 

EXAMPLES The following script opens the "names" file, reads a line from the file, 

and transmits the name to the SUT with the Type { ) function. Then it 
closes the "names" file, opens the "numbers" file, reads a line from this 
file, and transmits the number to the SUT with the Type { ) function. 
The "numbers" file also is closed with Fioclose ( ) . 
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Fioopen ( "names " , "r " ) ; 
Fioreadline ( "names " ) ; 
Type("%s", FIOBUFFER) ; 
Fioclose { "names " ) ; 

Lef tButtonPress (360, 211) ; 



AppWait(0.06) ; 
WindowRcvC'SfSfPt") ; 

Fioopen { "numbers" , "r") ; 
Fioreadline { "numbers " ) ; 
Type { " %s " , FIOBUFFER) ; 
Fioclose ( "numbers" ) ; 



SEE ALSO Fioopen 
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FUNCTION 



Fiodelimiter 



SYNTAX 



Fiodelimiter ( filename , delimiters ) 

char * filename; 

unsigned char * delimiters; 



DESCRIPTION Parameters 

filename The file for the operation 

delimiters The field delimiters for the specified file 
Comments 

See the description under File Input/Output Functions for a general 
explanation of these functions. 

The Fiodelimiter () function defines the field delimiters for the file 
filename. The default is "\t\n M where "\n" is always a delimiter ("\t" 
is tab and "\n" is new line or linefeed). 



RETURN VALUE If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 



EXAMPLES The following example illustrates using the functions 

Fioreadf ield( ) and Fioreadf ields ( ) to read one or more fields 
from a file. Fiodelimiter ( ) specifies that the field delimiter in the file 
inputf ile is a comma (Some script content was left out for brevity.) 
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char last [20] ; 
char first [20] ; 



Fioopen{ "inputfile" , "r" ) ; 
Fiodelimiter { " inputfile" , " , " ) ; 
Fioreadf ield ( " inputfile" ) ; 
Type("%s", FIOBUFFER) ; 

LeftButtonPress (360, 211) ; 



AppWait (0.06) ; 
WindowRcvt "Sf Sf Pt" ) ; 

Fioreadf ields ( " inputfile" , 2, last, first); 
TypeC%s" , last) ; 

LeftButtonPress (357,252) ; 



AppWait (0.06) ; 
WindowRcvC'SfSfPt") ; 

Type( "%s" , first) ; 



The following is a portion of the file inputfile; 



312890463 
doe, jane 
294028190 
smith, john 



SEE ALSO Fioreadfield, Fioreadfields, Fioskipfield 
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Fioopen 



SYNTAX Fioopen (filename, mode) 

char * filename, *mode; 

DESCRIPTION Parameters 

filename The file to be opened 

mode The mode for opening the file 
Comments 

See the description under File Input/Output functions for a general 
explanation of these functions. 

The Fioopen ( ) function opens the file filename. The parameter mode 
specifies how the file is opened. The following list demonstrates how 
the file is opened by specifying different mode parameters: 



Mode How File Is Opened 

r Opened at the beginning for reading only 

w Truncated or created for writing only 

a Opened at the end for writing only 

r+ Opened at the beginning for reading and writing 

w+ Truncated or created for reading or writing 

a+ Opened at the end for reading and writing 



Most of the File Input/Output functions will open the file automatically if 
it has not been opened previously with Fioopen { ). If you plan to write 
to a file, be sure to call Fioopen ( ) with the appropriate mode. 

RETURN VALUE If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 

EXAMPLES The following script opens the "names" file, reads a line from the file, 

and transmits the name to the SUT with the Type ( ) function. Then it 
closes the "names" file, opens the "numbers" file, reads a line from this 



EMPOWER/CS-Vl.0.1 



2-90 

Copyright PERFORMIX, Inc. © 1995 



User's Guide— Reference 



file, and transmits the number to the SUT with the Type ( ) function. 
The "numbers" file is also closed with Fioclose ( ) . 



Fioopen ( " names " , " r " ) ; 
Fioreadline ( "names " ) ; 
Type( M %s", FIOBUFFER); 
Fioclose ( "names " ) ; 

LeftButtonPress (360,211) ; 



AppWait (0.06) ; 
WindowRcvpSfSfPt" ) ; 

Fioopen { "numbers" , "r" ) ; 
Fioreadline ( "numbers" ) ; 
Type { " %s " , FIOBUFFER) ; 
Fioclose ( "numbers " ) ; 



Fioclose 
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FUNCTION 



Fioreadchar 



SYNTAX 



Fioreadchar { filename, n) 
char * filename; 
int n; 



DESCRIPTION Parameters 

filename The file for the operation 



n 



The number of bytes to read from the specified file 



Comments 

See the description under File Input/Output functions for a general 
explanation of these functions. 

The Fioreadchar { ) function reads n bytes from the file filename. If 
the file is not currently open, it is opened by Fioreadchar. A pointer to 
fiobuffer is returned. If fiolen is less than or equal to zero, then 
either an error occurred or the end-of-file was reached. 

RETURN VALUE This function returns a pointer to the global variable fiobuffer. 



EXAMPLES The following statements are used to read 10 characters from the 

"letters" file and send them to the SUT: 



Fioreadchar { " letters § 10 ) ; 
Type ( " %s " , FIOBUFFER) ; 



SEE ALSO 



Fioclose, Fioopen, Fioreadfield, Fioreadfields, Fioreadline 
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FUNCTION 



Fioreadfield 



SYNTAX 



Fioreadfield ( filename) 
char * filename ; 



DESCRIPTION Parameters 

filename The file to be used for the operation 

Comments 

See the description under File Input/Output functions for a general 
explanation of these fucntions. 

The Fioreadfield ( ) function reads the next field from the file 
filename into fiobuffer. The fields are separated by the delimiter. If 
the file is not currently open, it is opened automatically. A pointer to 
fiobuffer is returned. If fiolen is less than or equal to zero, then 
either an error occurred or the end-of-file was reached. 



RETURN VALUE This function returns a pointer to the global variable fiobuffer. 



EXAMPLES The following example illustrates using the functions 

Fioreadf ield{ ) and Fioreadf ields ( ) to read one or more fields 
from a file. Fiodelimiter () is used to specify that the field delimiter 
in the file input file is a comma. (Some script content was left out for 
brevity.) 
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char last [20] ; 
char first [20] ; 



Fioopen( "inputfile" , "r" ) ; 
Fiodelimiter ( "inputfile" , " , " ) ; 
Fioreadf ield ( " inputfile" ) ; 
Type ( 11 %s " , FIOBUFFER) ; 

Lef tButtonPress (360, 211) ; 



AppWait (0.06) ; 
WindowRcv{ "SfSf Pt" ) ; 

Fioreadf ields (" inputfile " , 2, last, first); 
Type("%s n , last); 

LeftButtonPress{357,252) ; 



AppWait (0.06) ; 
WindowRcv( "SfSfPt " ) ; 

Type{"%s" , first) ; 



The following is a portion of the file inputfile: 



312890463 
doe , j ane 
294028190 
smith, john 



SEE ALSO Fioclose, Fiodelimiter, Fioopen, Fioreadchar, Fioreadfields, Fioreadline 
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FUNCTION 



Fioreadfields 



SYNTAX 



Fioeadfields (filename, n, argO, 
char * filename; 
int **n; 

char *arg[n] 



. . , arg[n] ) 



DESCRIPTION Parameters 

filename The file to be used for the operation 

n The number of fields to read 

args The arguments where read fields are copied 

Comments 

This function reads n fields from the file filename as delimited by field 
delimiters. The default is " \t\n M , where "\t" is a tab and " \n" is 
always a delimiter. The fields are copied into arguments. If the file 
specified in filename is not currently opened, this function 
automatically opens it for reading. 



RETURN VALUE A pointer to fiobuffer is returned. If fiolen is less than or equal to 
zero, then either an error occurred or the end-of-file was reached. 



EXAMPLES The following example illustrates using the functions 

Fioreadf ield{ ) and Fioreadfields ( ) to read one or more fields 
from a file. Fiodelimiter ( ) is used to specify that the field delimiter 
in the file input f ile is a comma. (Some script content was left out for 
brevity.) 
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char last [20] ; 
char first [20] ,- 



Fioopen(" input file" , "r") ; 
Fiodelimiter ( "inputfile" , " , " ) ; 
Fioreadf ield{ "input file" ) ; 
Type ( " %s " , FIOBUFFER) ; 

LeftButtonPress<360,211) ; 



7™^ 



AppWait (0.06) ; 
WindowRcv{ "Sf Sf Pt" ) ; 

Fioreadfields ( "inputfile" , 2, last, first) 
Type( H %s" , last); 

LeftButtonPress(357,252) ; 



AppWait (0.06) ; 
WindowRc v ( " S f S f P t " ) 



Type( "%s" , first) ; 



The following is a portion of the file inputfile: 



312890463 
doe, jane 
294028190 
smith, john 



SEE ALSO Fioclose, Fiodelimiter, Fioopen, Fioreadchar, Fioreadfield, Fioreadline 
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FUNCTION 



Fioreadline 



SYNTAX 



Fioreadline (filename) 
char * filename; 



DESCRIPTION Parameters 

filename The file to be used for the operation 

Comments 

See the description under File Input/Output Functions for a general 
explanation of these functions. 

The Fioreadline { ) function reads the next line from the file 
filename into fiobuffer. If the file is not currently open, it is opened 
automatically. A pointer to fiobuffer is returned. If fiolen is less than 
or equal to zero, then either an error occurred or the end-of-file was 
reached. 

RETURN VALUE This function returns a pointer to the global variable fiobuffer. 

EXAMPLES The following script opens the "names" file, reads a line from the file, 

and transmits the name to the SUT with the Type ( ) function. Then it 
closes the "names" file, opens the "numbers" file, reads a line from this 
file, and transmits the number to the SUT with the Type ( ) function. 
The "numbers" file is also closed with Fioclose ( ) . 



Fioopen { " names " , r " ) ; 
Fioreadline ( "names " ) ; 
Type ( " %s " , FIOBUFFER) ; 
Fioclose ( "names " ) ; 

Lef tButtonPress (360, 211) ; 



(continued on following page ...) 



EMPOWER/CS-Vl.0.1 



2-97 

Copyright PERFORMIX. Inc.© 1995 



User's Guide— Reference 



AppWait(0.06) ; 
WindowRcv ( " Sf Sf Pt " ) ; 

Fioopen ( " numbers " , " r " ) ; 
Fioreadline ( "numbers " ) ; 
Type("%s", FIOBUFFER) ; 
Fioclose { "numbers " ) ; 



SEE ALSO Fioclose, Fioopen, Fioreadchar, Fioreadfield, Fioreadfields 
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FUNCTION 



Fiorewind 



SYNTAX 



Fiorewind { filename ) 
char * filename; 



DESCRIPTION Parameters 

filename The file to be used for the operation 

Comments 

See the description under File Input/Output Functions for a general 
explanation of these functions. 

The Fiorewind () function rewinds the file pointer to the beginning of 
the file specified in filename. 

RETURN VALUE If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 

EXAMPLES The following examples show you how to use the rewind functions to 

reuse data in an input file. Notice that Fioautorewind( ) saves you 
some programming because you do not have to check to see if you are 
at the end of the file: 



Fioaut orewind { " info " ) ,- 
Fioreadline( "info" ) ; 
Type ( " %s " , FIOBUFFER) ; 



OR 
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Fioreadline( "info" ) ; 
if (FI0LEN==-1) { 
Fiorewind ( " info " ) ; 
Fioreadline ( "info" ) ,- 
} 

Type { " % S " , FIOBUFFER ) ; 



SEE ALSO Fioautorewind, Fioclose, Fioseek 
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FUNCTION 



Fioseek 



SYNTAX 



Fioseek ( filename, offset} 
char * filename; 
long offset; 



DESCRIPTION Parameters 

filename The file to be used for the operation 

offset The offset of bytes from the beginning of the file 

Comments 

See the description under File Input/Output functions for a general 
explanation of these functions. 

The Fioseek ( ) function sets the file pointer to a specific byte in the 
file. The next byte read or written will occur at of f set bytes from the 
beginning of the file. If the value of offset is equal to fioend, the 
seek will continue to the end of the file. 

RETURN VALUE If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 



SEE ALSO 



Fioautorewind, Fioclose, Fiorewind 
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FUNCTION 



Fioshare 



. SYNTAX 



Fioshare { filename) 
char * filename ; 



DESCRIPTION 



Parameters 



filename The file to be shared 



Comments 

See the description under File Input/Output functions for a general 
explanation of these functions. 

The Fioshare () function identifies a file that is to be shared. It must 
be called before any other File I/O functions are called to reference the 
same file. Fioshare in a script presumes execution of the fioshare 
command at the UNIX script driver's shell prompt. The fioshare 
command creates a global variable that contains the offset for the next 
byte to be read from a shared file. 

The value of the variable (offset) remains between tests, so you can 
continue to read an input file from the point left by the previous test. 
This saving of the offset is useful in tests that corrupt a database on the 
server. The ability to avoid the same transactions means you can avoid 
restoring the database before every test. You must execute the 
fioshare command if you want to resume reading from the beginning 
of the input file. For this reason, fioshare often is run from Mix 
command files that set up for a new test 

If your file to be shared includes database fields, you must be sure to 
use the Gv_protect ( ) function to protect the database fields. 



RETURN VALUE If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 



EXAMPLES 



Assume we require scripts to read commands from an input file called 
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cmds. The following command will create the global offset for the file: 

$ fioshare cmds 

A segment in the script to read from cmds might look like the following. 
Each instance of this script will read different lines in the cmds file: 



Fioshare ( " cmds " ) ; 

Fioreadline ( "cmds" ) ; 
if {FIOLEN == -1) 
{ 

Logpend of the date file*'); 
exit (1) ; 

} 

Type (FIOBUFFER, " A M" , " 11 ) ; 
} 



The global offset is stored in a Global Variable. This Global Variable's 
name is the inode of the shared file which can be confirmed by typing 
the UNIX is -i command with an argument of the shared file and then 
by executing the gv_stat command. This command lists the name, 
status, and value of EMPOWER/CS global variables. For example: 



$ fioshare cmds 




$ Is -i cmds 




59449 cmds 




$ gv_stat 




gv_stat: EMPOWER /GV VI 


0.1, Serial#ROOOOO-000, Copyright PERFORMIX, Inc. 


1988-95 




Name Type 


Value Allocated Protector 


59449 long int 


0 0 



SEE ALSO Fioclose, Fiounshare, gv_stat 
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FUNCTION Fioskipchar 

SYNTAX Fioskipchar ( filename , n) 

char * filename; 
int n; 

DESCRIPTION Parameters 

filename The file to be used for the operation 

n The number of characters to skip forward in the specified file 

Comments 

See the description under File Input/Output Functions for a general 
explanation of these functions. 

The Fioskipchar ( ) function skips forward n characters in the file 
filename. If the file is not currently open, it is opened automatically by 
Fioskipchar () . The variables FIOBUFFER and fiolen are updated 
with the last characters read (the number of characters used to update 
fiobuffer and fiolen is defined by the variable fiobuffersz). 

RETURN VALUE If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 

SEE ALSO Fioclose, Fioopen, Fioskipfield, Fioskipline 
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FUNCTION Fioskipfield 

SYNTAX . Fioskipfield{ filename, n) 

char * filename; 
int n; 



DESCRIPTION Parameters 

filename The file to be used for the operation 

n The number of fields to skip forward in the specified file 



Comments 

See the description under File Input/Output Functions for a general 
explanation of these functions. 

The Fioskipfield ( ) function skips forward n fields in the file 
filename. The fields are separated by the delimiter. If the file is not 
currently open, it is opened automatically. The variables fiobuffer and 
fiolen are updated with the last field read. 

RETURN VALUE If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 

SEE ALSO Fioclose, Fiodelimiter, Fioopen, Fioskipchar, Fioskipline 



EMPOWER/CS-Vl.0.1 



2-105 



Copyright PERFORMIX, Inc. © 1995 



User's Guide— Reference 



FUNCTION 
SYNTAX 



Fioskipline 



Fioskipline ( filename, n) 
char * filename; 
int n; 



DESCRIPTION Parameters 

filename The file to be used for the operation 

n The number of lines to skip forward in the specified file 

Comments 

See the description under File Input/Output Functions for a general 
explanation of these functions. 

The Fioskipline ( ) function skips forward n lines in the file 
filename. If the file is not currently open, it is opened automatically 
with Fioskipline () . The variables fiobuffer and fiolen are 
updated with the last line read. 

RETURN VALUE If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 



SEE ALSO 



Fioclose, Fioopen, Fioskipchar, Fioskipfield 
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FUNCTION 



Fiounshare 



SYNTAX 



Fiounshare ( filename) 
char * filename; 



DESCRIPTION 



Parameters 
filename 



The file to be used for the operation 



Comments 

See the description under File Input/Output Functions for a general 
explanation of these functions. 

The Fiounshare () function and the fiounshare shell command 
discontinue the sharing of a file. Neither the function nor the command 
remove the global variable offset for the file. They simply mark the 
global variable as being unusable for further Input/Output functions. 

The Fiounshare function disables the sharing of the file offset only for 
the script that executes the function, and the fiounshare shell 
command disables the sharing of the file offset for all scripts currently 
sharing the file* 

To remove the global variable offset, you must use the gv_rm shell 
command to remove the variable. 

For example: 

$ gv_rm -f 59449 

RETURN VALUE If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 



SEE ALSO 



Fioclose, Fioshare, gv_rm, gv_stat 
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FUNCTION 



Fiowritechar 



SYNTAX 



Fiowritechar ( filename, buf, n) 
char * filename, *buf; 
long n; 



DESCRIPTION Parameters 

filename The file to be used for the operation 



buf 



n 



The file buffer 

The number of bytes from the buffer 



Comments 

See the description under File Input/Output Functions for a general 
explanation of these functions. 

The Fiowritechar ( ) function writes n bytes from the buffer, buf, to 
the file filename. If the file is not currently open, it automatically is 
created or truncated and opened for reading and writing. 

RETURN VALUE If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 



SEE ALSO 



Fioclose, Fioopen 
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FUNCTION 



GetNextRow 



SYNTAX 



GetNextRow { curnum) 



int curnum; 



DESCRIPTION Parameters 

curnum An identifier of a cursor communication structure 



Comments 

The GetNextRow ( ) function is inserted into your script after a Fetch { ) 
function when the client application sorts through the fetched rows of 
data 

During script execution, when the number of rows of data specified in 
the Dbset ( ) option fetchsize are fetched from the database, the data 
is placed into output variables in a buffer file on your UNIX driver 
machine. GetNextRow ( ) sorts through the rows one at a time after they 
are fetched onto the UNIX script driver. This function generally occurs 
in a loop and may be used to verify that the requested data was 
retrieved or locate a specific row of data 

Note: Because this function is inserted into your script based on how 
the client application interacts with the SUT, you should not attempt to 
edit this function or remove it from the script. If you change this 
function from when it was captured in the script file, you may drastically 
alter the expected behavior of the application and SUT and therefore, 
break your script during execution. 



RETURN VALUE GetNextRow { ) returns a string representation of the row retrieved. 



query in a script file. The query was generated on the cursor, curi. The 
EMPOWER/CS function GetNextRow {) was inserted after the 
Fetch ( ): 



EXAMPLES 



The following example demonstrates the execution of a database 
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Parse {CURl, " SELECT EMPNO, ENAME, JOB, MGR, HIREDATE, 
SAL, COMM, DEPTNO FROM EMP, UPDATE OF EMPNO, ENAME , 
JOB , MGR, HIREDATE, SAL, COMM, DEPTNO" ) ; 



Define (CUR1, 


"1" , 


STRING, 


5) ; 


Define (CUR1, 


" 2 " , 


STRING, 


11) ; 


Define (CURl, 


" 3 " , 


STRING, 


10) ; 


Define (CURl, 


" 4 " , 


STRING, 


5) ; 


Define (CURl, 


"5", 


STRING, 


10) ; 


Define (CURl, 


"6" , 


STRING, 


9); 


Define (CURl, 


"7", 


STRING, 


9); 


Define (CURl, 


"8", 


STRING, 


3) ; 



Exec (CURl) ; 

Fetch (CURl) ; 
GetNextRow(CURl) ; 



SEE ALSO Fetch 
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FUNCTION GetlntVar 

SYNTAX GetlntVar (curnum, var) 

int curnura; 
char *var ; 

DESCRIPTION Parameters 

curnum A cursor communication structure 

var The name of the variable listed in the Parse ( ) statement 

Comments 

You can insert GetlntVar ( ) into your script file to return the current 
value of the specified variable that was listed in the Parse { ) statement. 

This function should be inserted into the script after the Fetch ( ) and 
GetNextRowO functions. 

RETURN VALUE This function returns an integer for the current value of the variable. 
EXAMPLES The following example demonstrates using GetlntVar ( ) within a script: 



int empno; 






Parse (CUR1, 


"select ename 


, empno from employee_table" ) ; 


Define (CUR1, 


"1", STRING t 


50); 


Define (CUR1, 


"2", INT, 4) 


r 


Exec (CUR1) ; 










(continued on the following page ...) 
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Dbset(CURl, FETCHSIZE, 1); 
while (Fetch (CURD != 0) { 

GetNextRow(CURl) ; 

empno=GetIntVar ( CURl , "2") ; 

printf ( "empno is %d\n", empno); 

} 



SEE ALSO 



CmpVar, GetVar, SetlntVar, SetVar 
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FUNCTION QetVar 

SYNTAX' GetVar (curnum, var) 

int curnum; 
char * var ; 



DESCRIPTION Parameters 

curnum A cursor communication structure 

var The name of the variable 



Comments 

You can insert the GetVar { ) function into your script to return the 
current value of the variable specified in the Parsed statement (as 
either the name or position) 

This function should be inserted after the Fetch () or GetNextRowO 
functions. 



RETURN VALUE This function returns a string for the current value of the specified 
variable. 



EXAMPLES 



The following example demonstrates using GetVar ( ) within a script 



char * empname , * empno ; 



Parse (CUR1, "select ename, empno from employee_table" ) ; 

Define{CURl, "1", STRING, 50); 
Define (CUR1, "2", INT, 4) ; 

Exec (CUR1) ; 

(continued on following page . . .) 
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Dbset(CURl, FETCHSIZE, 1) 




while (Fetch(CURl) != 0){ 




GetNextRow(CURl) ; 




empname=GetVar {CUR1 , " 1 " 


) ; 


print f ( " empname is %s\n" 


, empname) ; 


empno=Ge tVar { CUR1 , " 2 " ) ; 




print f { " empno is %d\n" , 

} 


* { int * ) empno) ; 



SEE ALSO GetlntVar, SetlntVar, SetVar 
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COMMAND gv_add 

SYNTAX gv„add name value 

DESCRIPTION The gv_add command is entered at the command line and updates 

the value of a specified variable by adding a specified amount to the 
variable's current value. The parameter value is the operand for the 
operation. When this command is entered, the original value is written 
to the standard output destination before the new value, based on 
operation results, is assigned. 



This command operates on all variable types except strings. 



RETURN CODE 



If the command succeeds, the return code is set to zero. If an error 
occurs, the return code is set to one and an error message is sent to the 
standard error destination. 



EXAMPLES In the following example, suppose the variable users has a value of 5 

and you wish to change the value by adding 4. The interaction would 
be as follows: 



$ gv_add users 4 

5 

$ gv_read users 

9 



SEE ALSO 



Gv add 
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FUNCTION Gv__add, Gv_addv 

SYNTAX int Gv_add(name, value) 

char *name; 
int value; 



int Gv_addv ( name , value, oldvalue) 
char *name; 



DESCRIPTION Parameters 

name The name of the global variable 

value The operand for the operation 

oldvalue The pointer location where the original value should be 
stored 



Comments 

The Gv_add function updates the value of a specified variable by 
adding a specified amount to the current value of a variable. You can 
insert these functions into your script when editing the script file. 

Gv_add ( ) is used if the variable is an integer, and Gv_addv ( ) is used if 
the variable is not an integer. 

RETURN VALUE Gv__add { ) returns the original value of the specified variable. 

Gv_addv ( ) copies the original value to a pointer location. After the 
value of the variable has been updated, the original value, cast as an 
integer, is returned If an error occurs, the script exits and an error 
message is sent to the standard error destination. 

EXAMPLES The following example demonstrates using Gv_add{ ) in a script file. 

In this example, if the variable customer is equal to zero, then 2 will be 
added to the current value of the variable users. 
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if (customer — 0) 
Gv__add ( users , 2 } ; 



SEE ALSO 



gv_add 
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FUNCTION 



Gv alloc 



SYNTAX 



void Gv_alloc (name, type) 
char *name, *type; 



DESCRIPTION 



Parameters 



name 



The name of the global variable 



type 



The global variable type 



Comments 

The Gv_alloc() function allocates the script's access to the specified 
global variable. Access should be allocated for a variable so that a script 
can use the variable in subsequent Global Variable functions. The 
Gv_alloc { ) function should be the first function in the script if the 
script references a global variable. 

An error will result if the name and type parameters of the Gv_alloc ( ) 
function do not match the actual name and type of the variable specified 
when the variable was created with the gv_init command 

An error will result if the specified global variable does not exist, if the 
specified variable type does not match the global variable type, or if the 
global variable has already been allocated to the script 

If an error occurs, the script exits and an error message is sent to the 
standard error destination. 



RETURN VALUE (not applicable) 



EXAMPLES 



To allocate a script's access to the variable users which is an integer 
type, the following function must be included in the script file: 



Gv_alloc ("users " , "int") ; 
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The variable users must be initialized at the shell prompt: 
$ gv_init user int 50 

SEE ALSO Gv_free, gv_init 
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COMMAND 



gv_and 



SYNTAX 



gv_and name value 



DESCRIPTION The gv_and command is entered at the shell prompt and updates the 



value of a specified variable by applying a bit-wise AND masking 
operation to the variable. The parameter value is the operand for the 
operation. When this command is entered, the original value is written 
to the standard output destination before the new value, based on 
operation results, is assigned. 

This command operates on all variable types except strings. 



RETURN CODE If the command succeeds, the return code is set to zero. If an error 

occurs, the return code is set to one and an error message is sent to the 
standard error destination. 



SEE ALSO 



Gv and 
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FUNCTION Gv_and, Qv_andv 

SYNTAX int Gv_and ( name , value) 

char *name ; 
int value; 

int Gv_andv ( name , value, oldvalue) 
char *name; 

DESCRIPTION Parameters 

name The name of the global variable 

value The operand for the operation 

oldvalue The pointer location where the original value should be 
Stored (Gvjandv ( ) ) 

Comments 

The Gv_and ( ) and Gv„andv ( ) functions update the value of a 
specified variable by applying a bit-wise AND masking operation to the 
variable. You can insert these functions into your script when editing. 

Gv_and ( } is used if the variable is an integer and Gv_andv ( ) is used if 
the variable is not an integer. 



RETURN VALUE 



Gv_and{ ) returns the original value of the specified variable and 
Gv_andv ( ) copies the original value to a pointer location. After the 
value of the variable has been updated, the original value, cast as an 
integer, is returned. If an error occurs, the script exits and an error 
message is sent to the standard error destination. 



SEE ALSO 



gv_and 



EMPOWER/CS-Vl.0.1 



2-121 

Copyrighl PERFORMIX, Inc. © 1995 



User's Guide— Reference 



COMMAND 

SYNTAX 

DESCRIPTION 



RETURN CODE 



gv_dec 

gv_dec name 

The gv_dec command is entered at the shell prompt and decreases 
the value of the specified variable by one. When the gv_dec command 
is entered, the original value is written to the standard output destination 
before the new, decremented value is assigned. 

If the command succeeds, the return code is set to zero. If an error 
occurs, the return code is set to one and an error message is sent to the 
standard error destination. 



EXAMPLES In the following example the current value of the variable count is 5. 

To decrease this value by one use the following gv_dec command. 
Then, use the gv_read command to get the new value of the variable: 



$ 


gv_dec 


count 


5 






$ 


gv_read 


count 


4 







SEE ALSO 



Gv_dec, Gv_inc, gv_inc 
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FUNCTION 



Gv_dec, Gv__decv 



SYNTAX 



int Gv_dec ( name ) 
char *name; 



int Gv_dec v ( name , value) 
char *name ; 

DESCRIPTION Parameters 

name The name of the global variable 

value The pointer location where the original value should be 
stored (for Gv_decv ( ) ) 

Comments 

The Gv_dec ( ) and Gv_decv ( ) functions update the value of a 
specified variable by subtracting one from the current value. Gv_dec ( ) 
is used if the variable is an integer, and Gv_decv() is used if the 
variable is not an integer. 



RETURN VALUE 



The Gv_dec ( ) function returns the original value of the specified 
variable and the Gv__decv { ) function copies the original value to a 
pointer location. After the value of the variable has been decremented, 
the original value, cast as an integer, is returned. If an error occurs, the 
script exits and an error message is sent to the standard error 
destination. 



EXAMPLES The following example shows that if the new value of global "amount" 

is zero then the script calls function "c!ose_account". The script gets the 
new value of "amount" by subtracting one from the current value. 



if (Gv_dec(" amount ") == 0) 
close_account ( ) ; 



SEE ALSO 



Gv_inc, Gv_incv, gv_dec, gv_inc 
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COMMAND gv_div 

SYNTAX gv_div name value 

DESCRIPTION The gv_div command is entered at the shell prompt and updates the 

value of a specified variable by dividing the variable's current value by 
a specified amount. The parameter value is the operand for the 
operation. When this command is entered, the original value is written 
to the standard output destination before the new value, based on 
operation results, is assigned. 



RETURN CODE 



This command operates on all variable types except strings. 

If the command succeeds, the return code is set to zero. If an error 
occurs, the return code is set to one and an error message is sent to the 
standard error destination. 



EXAMPLES In the following example, suppose the variable users has a current 

value of 8 and you wish to change the value by dividing it by 4. The 
interaction would be as follows: 




SEE ALSO 



Gv div 
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FUNCTION Gv_div, Gv_divv 

SYNTAX int Gv_div(naine / value) 

char *name; 
int value; 

int Gv_diw{name, value, oldvalue) 
char *name; 

DESCRIPTION Parameters 

name The name of the global variable 

value The operand for the operation 

oldvalue The pointer location where the original value should be 
stored (for Gv_di w ( ) ) 

Comments 

The Gv_div{) and Gv_diw{) functions update the value of a 
specified variable by dividing the current value of the variable by a 
specified amount. You can insert this function into your script when 
editing the script file. 

Gv_d-iv { ) is used if the variable is an integer, and Gv_diw ( ) is used if 
the variable is not an integer. 



RETURN VALUE 



Gv_di v { ) returns the original value of the specified variable and 
Gv_diw ( ) copies the original value to a pointer location. After the 
value of the variable has been updated, the original value, cast as an 
integer, is returned. If an error occurs, the script exits and an error 
message is sent to the standard error destination. 



SEE ALSO 



gv div 
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FUNCTION Gv_free 

SYNTAX void Gv_f ree (name) 

char *name ; 

DESCRIPTION Parameters 

name The name of the global variable 

Comments 

The Gv_f ree ( ) function de-allocates a scripts access to a specified 
variable. This function can be inserted into your script file when editing. 

The script will not execute Global Variable functions for a variable that 
has been de-allocated unless access is re-allocated If a script attempts to 
de-allocate a variable with Gv_free() and the variable has been 
protected by the script, the variable will be unprotected before the 
Gv_f ree { ) function completes. 

Note: Using the Gv_f ree ( ) function is optional. When a script exits, all 
allocated global variables will de-allocate automatically. 

(not applicable) 

The following example demonstrates that the script allocates and 
reads the global variable amount, then it de-allocates access to the global 
variable with Gv_f ree ( ) . 



int number; 

Gv_alloc { "amount" ) ; 
number=Gv_read ( " amount " ) ; 
if (number > 10) 

order ( ) ; 
Gv_f ree ( 11 amount " ) ; 
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RETURN VALUE 



EXAMPLES 



User's Guide— Reference 



SEE ALSO Gv allocate 
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COMMAND 

SYNTAX 

DESCRIPTION 



gv__getparallel 



gv_getparallel name 



The gv_getparallel command is entered at the shell prompt and 
returns the current value of the specified parallel variable to the 
standard output destination. 



RETURN CODE 



If the command succeeds, the return code is set to zero. If an error 
occurs, the return code is set to one and an error message is sent to 
the standard error destination. 



EXAMPLES 



This example returns a value of 50 for the parallel variable workers: 



$ gv_getparallel workers 

50 



SEE ALSO Gv getparallel, Gv_parallel, Gv_setparallel, Gv_unparallel, gv__parallel, 

gv_setparallel, gv__unparallel 
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FUNCTION 



Gv_getparallel 



SYNTAX 



unsigned short int Gv_getparal lei (name) 
char *name; 



DESCRIPTION Parameters 

name The name of the global variable 

Comments 

The Gv_getparallel ( ) function returns the current value of the 
specified parallel variable. This function can be inserted into your script 
file when editing. 



RETURN VALUE 



The Gv_getparallel ( ) function returns the current value of the 
specified parallel variable. This value should be stored in a local variable. 
If the variable type read is not int, the variables current value is 
returned cast as an integer. If an error occurs, the script will exit and an 
error message is sent to the standard error destination. 



SEE ALSO Gv__parallel, Gv_setparallel, Gv_unparallel, gv getparallel, gv_parallel, 

gv_setparallel, gv_unparallel 
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COMMAND 

SYNTAX 

DESCRIPTION 



RETURN CODE 



gv_inc 



gv_mc name 



The gv„inc command is entered at the shell prompt and increases 
the value of the specified variable by one. When the gv_inc command 
is entered, the original value is written to the standard output destination 
before the new, incremented value is assigned. 

If the command succeeds, the return code is set to zero. If an error 
occurs, the return code is set to one and an error message is sent to the 
standard error destination. 



EXAMPLES In the following example, the current value of the variable count is 5. 

To increment the value by one use the following gv_inc command. 
Then, enter a gv_read command to get the new value: 



$ gv_inc count 

5 

$ gv_read count 

6 



SEE ALSO 



Gv_dec, Gv_jnc, gv_dec 



EMPOWER/CS-Vl.0.1 



2-130 



Copynghl PERFORMIX. Inc.© 1995 



User's Guide— Reference 



FUNCTION 



Gv_inc, Gv_incv 



SYNTAX 



int Gv_inc (name) 
char *name; 



int Gv_incv(name, value) 
char *name ; 

DESCRIPTION Parameters 

name The name of the global variable 

value The pointer location where the original value should be 
stored (for Gv_incv ( ) ) 

Comments 

You can insert these functions into your script file when editing. 

The Gv_inc() and Gv_incv() functions update the value of the 
specified variable by adding one to the current value. Gv_inc { ) is used 
if the variable is an integer, and Gv_incv ( ) is used if the variable is not 
an integer. 



RETURN VALUE 



The Gv_inc { ) function returns the original value of the specified 
variable and the Gv_incv{) function copies the original value to a 
pointer location. After the value of the variable has been incremented, 
the original value, cast as an integer, is returned. If an error occurs, the 
script exits and an error message is sent to the standard error 
destination. 



EXAMPLES The following example can be used to increment the integer variable 

count: 



Gv_alloc ( " count " , " int " ) 
Gv_inc ( M count " ) ; 
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To increment the non-integer variable balance, the following example can be used: 



float curbalance; 




Gv_alloc ( "balance" 


, "float"); 


Gv_incv( "balance" , 


&curba lance) ; 



SEE ALSO Gv_dec, Qv_decv, gv_dec, gv_inc 



§1 

m 

s 

0 

ry 
m 

o 
o 



EMPOWER/CS-Vl.0.1 



2-132 



Copyright PERFORMIX. Inc. 0 1995 



User's Guide— Reference 



COMMAND gv__init 

SYNTAX gv_init name [type] value 

DESCRIPTION The gv_init command is entered at the shell prompt and is used to 

initialize a variable. If the variable does not exist, it is created with the 
specified type and initial value. If the variable exists when the gv_init 
command is entered, the variable is reset to the specified value. 

The parameter type is required if the variable does not exist. If the 
variable exists, the parameter type is optional and the type and value 
specified in gv_init must correspond to the existing variable type. If a 
different type is specified or if the new value specified does not 
correspond to the existing type, the command fails. 

The default maximum number of variables is 128. The maximum length 
of a variable name is 14 characters. The maximum length of the value of 
a string variable is 32 characters. 

If the command succeeds, the return code is set to zero. If an error 
occurs, the return code is set to one and an error message is sent to the 
standard error destination. 

The gv_init command creates a variable with a specified name, 
variable type, and initial value. In the following example, gv_init is the 
Global Variable command, customer is the variable name, int specifies 
that customer is an integer, and 100 is the initial value of the variable 
customer. 

$ gv_init customer int 100 

To specify the same variable as a parallel variable, you would enter the 
following: 

$ gv_init customer parallel 100 
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RETURN CODE 



EXAMPLES 



User's Guide— Reference 



Global variables generally are created at the UNIX driver machine with 
the gv_init command, then accessed in a script with the Gv_alloc ( ) 
function: 

To use the following variable users during script execution: 

$ gv_init users int 0 
The following function should be included in the script: 
Gv_alloc ( "users" , "int" ) ; 
^ SEE ALSO Gv_alIoc, gv_seg 

. irfs 
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COMMAND 

SYNTAX 

DESCRIPTION 



RETURN CODE 



gv__lshift 

gv_l shift name value 

The gv_lshif t command is entered at the shell prompt and updates 
the value of a specified variable by performing a bit-wise shift to the 
left on a variable. The parameter value is the operand for the operation. 
When this command is entered, the original value is written to the 
standard output destination before the new value, based on operation 
results, is assigned. 

This command operates on all variable types except strings. 

If the command succeeds, the return code is set to zero. If an error 
occurs, the return code is set to one and an error message is sent to the 
standard error destination. 



SEE ALSO 



Gv_Jshift, Gv_rshift 
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FUNCTION 



Gvjshift, Gvjshiftv 



SYNTAX 



int Gv__lshif t (name, value) 
char *name; 
int value; 



int Gv_lshif tv(name, value, oldvalue) 
char *name; 

DESCRIPTION Parameters 

name The name of the global variable 

value The operand for the operation 

oldvalue The pointer location where the original value should be 
stored (for Gv__lshif tv { ) ) 

Comments 

These functions are used with the EMPOWER/GV tool and are inserted 
into your script file when editing. 

The Gv_lshif t ( ) and Gv_lshif tv( ) functions update the value of a 
specified variable by performing a bit-wise shift to the left on the 
variable, 

Gv_lshif t ( ) is used if the variable is an integer, and Gv__lshif tv( ) is 
used if the variable is not an integer. 

RETURN VALUE Gv_lshif t ( ) returns the original value of the specified variable and 

Gv_lshiftv() copies the original value to a pointer location. After the 
value of the variable has been updated, the original value, cast as an 
integer, is returned. If an error occurs, the script exits and an error 
message is sent to the standard error destination. 



SEE ALSO 



Gvjrshift, Gv_rshiftv, gv_lshift, gvjrshift 
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COMMAND gv_mod 

SYNTAX gv_mod name value 

DESCRIPTION The gv_mod command is entered at the shell prompt and updates the 

value of a specified variable by performing a modulo operation on a 
variable. The parameter value is the operand for the operation. When 
this command is entered, the original value is written to the standard 
output destination before the new value, based on operation results, is 
assigned. 

This command operates on all variable types except strings. 



RETURN CODE 



If the command succeeds, the return code is set to zero. If an error 
occurs, the return code is set to one and an error message is sent to the 
standard error destination. 



EXAMPLES In the following example, when count=10 and the user performs a 
modulo operation with 3, the new value of count is 1. 



$ gv_init count int 
$ gv_mod count 3 

10 

$ gv_read count 



10 
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When count=10 and the user performs a modulo operation with 2, the 
new value of count is 0. 



$ gv_init count int 10 
$ gv_mod count 2 

10 

$ gr_read count 

0 



SEE ALSO 



G v _JTiod, Gv_modv 
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FUNCTION 
SYNTAX 



DESCRIPTION 



RETURN VALUE 
SEE ALSO 



Gv__mod, Gv_modv 

int Gv„mod ( name , value) 
char *name; 
int value; 

int Gv_modv(name / value, oldvalue) 
char *name ; 

Parameters 

name The name of the global variable 
value The operand for the operation 

oldvalue The pointer location where the original value should be 
stored (for Gv_modv ( ) ) 

Comments 

The Gv_mod() and Gv_modv{) functions update the value of a 
specified variable by performing a modulo operation on the variable. 
You can insert these functions into your script when editing your script 
file. 

Gv_mod ( ) is used if the variable is an integer, and Gv_modv { ) is used if 
the variable is not an integer. 

Gv_mod{ ) returns the original value of the specified variable and 
Gv_modv ( ) copies the original value to a pointer location. After the 
value of the variable has been updated, the original value, cast as an 
integer, is returned. If an error occurs, the script exits and an error 
message is sent to the standard error destination. 

gv__mod 



EMPOWER/CS-Vl.0.1 



2-139 

Copyright PERFORMIX, Inc. © 1995 



User's Guide— Reference 



COMMAND 

SYNTAX 

DESCRIPTION 



RETURN CODE 



gv_mul 

gv_mul name value 

The gv_mul command is entered at the shell promt and updates the 
value of a specified variable by multiplying the variable's current value 
by a specified amount. The parameter value is the operand for the 
operation. When this command is entered, the original value is written 
to the standard output destination before the new value, based on 
operation results, is assigned. 

This command operates on all variable types except strings. 

If the command succeeds, the return code is set to zero. If an error 
occurs, the return code is set to one and an error message is sent to the 
standard error destination. 



EXAMPLES In the following example the current value of the variable users is 5. 

To change the value of this variable by multiplying by 10, use the 
following gv_mul command. Then, enter the gv_read command to get 
the changed value: 



$ gv_mul users 10 

5 

$ gv_read users 

50 



SEE ALSO 



Gvjnul, Gv_mulv 
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FUNCTION Gv_mul, Gv_mulv 

SYNTAX int Gv_mul{name, value) 

char *name; 
int value; 



int Gv_mu.lv (name, value, oldvalue) 
char *name ; 



DESCRIPTION Parameters 

name The name of the global variable 

value The operand for the operation 

oldvalue The pointer location where the original value should be 
stored (for Gv_mulv { ) ) 



Comments 

The Gv_mul ( ) and Gv_mulv{) functions update the value of a 
specified variable by multiplying the current value of the variable by a 
specified amount. You can insert these functions into your script file 
when editing. 

Gv_mul { ) is used if the variable is an integer, and Gv_mul v ( ) is used if 
the variable is not an integer. 

RETURN VALUE Gv_mul ( ) returns the original value of the specified variable and 

Gv_mulv() copies the original value to a pointer location. After the 
value of the variable has been updated, the original value, cast as an 
integer, is returned. If an error occurs, the script exits and an error 
message is sent to the standard error destination. 

EXAMPLES In the following example, the value of the variable count is multiplied 

by four. The value of count prior to the multiplication is stored in 
curcount: 
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int curcount; 

Gv_alloc ( " count " , " int " ) ; 

curcount = Gv_mul (" count " , 4) 



SEE ALSO 



gv_mul 
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COMMAND 

SYNTAX 

DESCRIPTION 



RETURN CODE 



gv_or 



gv_or name value 



The gv_or command is entered at the command line and updates the 
value of a specified variable by applying a bit-wise OR masking 
operation to the variable. The parameter value is the operand for the 
operation. When this command is entered, the original value is written 
to the standard output destination before the new value, based on 
operation results, is assigned. 

This command operates on all variable types except strings. 

If the command succeeds, the return code is set to zero. If an error 
occurs, the return code is set to one and an error message is sent to the 
standard error destination. 



SEE ALSO 



Gv or 
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FUNCTION 



Gv_or, Gv_orv 



SYNTAX 



int Gv_or (name, value) 



char *name ; 



int value; 



int Gv^rvtname, value, oldvalue) 



char *name ; 



DESCRIPTION 



Parameters 



name 



The name of the global variable 



value The operand for the operation 

oldvalue The pointer location where the original value should 
be stored (for Gv_orv ( } ) 

Comments 

The Gv_or ( ) and Gv_orv ( ) functions update the value of a specified 
variable by applying a bit-wise OR masking operation to the variable. 
These functions can be inserted in your script when editing the script 



Gv_or { ) is used if the variable is an integer, and Gv_orv( ) is used if 
the variable is not an integer. 



RETURN VALUE Gv_or ( ) returns the original value of the specified variable and 



Gv_orv ( ) copies the original value to a pointer location. After the value 
of the variable has been updated, the original value, cast as an integer, is 
returned. If an error occurs, the script exits and an error message is 
sent to the standard error destination. 



file. 



SEE ALSO 



gv__or 
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COMMAND gv__parallel 
SYNTAX gv__ parallel name 

DESCRIPTION The gv_parallel command is entered at the shell prompt and waits 

for the value of the specified parallel variable to become greater than 
zero then decrements the variable by one. When used in conjunction 
with the gv_unparallel command, the parallel variable becomes an 
"on/off switch to control multiple script execution. 



RETURN CODE 



If the command succeeds, the return code is set to zero. If an error 
occurs, the return code is set to one and an error message is sent to the 
standard error destination. 



SEE ALSO Gv_getparallel, Gv_parallel, Gv_setparallel, Gv_unparallel, 

gv__getparallel, gv__setparallel, gv_unparallel 
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FUNCTION Gv_parallel 

SYNTAX void Gv_paral lei (name) 

char *name; 

DESCRIPTION Parameters 

name The name of the global variable 



RETURN CODE 



Comments 

The Gv_parallel ( ) function waits for the value of the specified 
parallel variable to become greater than zero then decrements the 
variable by one. When used in conjunction with the Gv_unparaiiel ( ) 
function, the parallel variable acts as an "on/off switch to control 
multiple script execution. You can insert this function into your script 
file when editing. 

If the function succeeds, the return code is set to zero. If an error 
occurs, the script exits and an error message is sent to the standard 
error destination. 



EXAMPLES In this example, parallel Global Variables control execution of multiple 

scripts. Parallel variable commands and functions allow a subset of 
emulated users to execute a portion of the script at a given time. 
Specifically, during an emulation involving 500 users, a portion of the 
test may be executed in parallel by only 50 users. 

Each user will execute one script The Global Variable worker is created 
from the command line as a parallel type variable with an initial value of 
50: 



$ gv_init worker parallel 50 

The following script is executed by all users (some script content is left 
out for brevity): 
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login ( ) 

{/* login transactions - not detailed here */} 

Empower (argc, argv) 
int argc; 
char *argv[] ; 

{ 

Gv_alloc ( "worker" , "parallel " ) ; 
login () ; 

Beginscenario ( "example" ) ; 

/* ... numerous transactions */ 

Gv_parallel ( "worker" ) ; 

/* ... limited portion of transactions */ 
Gv_unparallel { "worker" ) ; 
/* ... numerous transactions */ 
Endscenar io ( " example " ) ; 

} 



The first 50 users to reach the Gv_parallel ( ) function during script 
execution immediately will execute the limited portion of transactions. 
The remaining 450 users will reach the Gv_parallel ( ) function and 
will wait 

As the 50th user executes the Gvj>arallel ( ) function, the value of 
the variable worker is decremented to zero. As each of the first 50 
scripts reaches the Gv_unparallel ( ) function, the value of worker is 
incremented to be greater than zero, so that one of the waiting scripts 
can execute the limited portion of transactions. This process ensures 
that only the first 50 scripts will execute the specified transactions at the 
same time. 
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SEE ALSO Gv qetparallel, Gv_setparallel, Gv_unparallel, gv getparallel, 

gv_parallel, gv_setparallel, gv_unparallel 
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COMMAND gv_protect 

SYNTAX gv_protect [-f] name 

DESCRIPTION The gv_protect command is entered at the shell prompt and 

prevents scripts access to a specified variable— only Global Variable 
Commands can access the- variable. Scripts that try to access a protected 
variable will pause until the variable has been unprotected. The - f 
option forces protection of the variable even if the variable currently is 
protected by a script 

If a script has protected a variable and gv_protect -f is executed 
from the shell to protect the variable, the script will execute as though it 
no longer protects the variable. The script will block, waiting for the shell 
to unprotect the variable. The Gv_unprotect ( ) function executed in 
the script has no effect (Note: The -f option of gv_protect is rarely 
used.) 

If the command succeeds, the return code is set to zero. If an error 
occurs, the return code is set to one and an error message is sent to the 
standard error destination. If the -f option is used to force protection of 
a variable, a warning message will be returned. 

EXAMPLES In this example, three scripts (si, s2, and s3) are started and 

synchronized by accessing a variable synch which is protected at the 
command line with the gv_protect command. Then, the variable is 
unprotected. The gv_stat command is used to demonstrate the 
variable being protected and then unprotected. The interaction could 
look like the following: 




^ RETURN CODE 
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$ gv_init synch 


int 0 








$ cry protect synch 








$ gv_stat 










Name 


Type 


Value 


Allocated 


Protector 


synch 


int 


0 


0 


CONSOLE 


$ si & 










[1] 3058 










si readv 










$ s2 & 










[2] 3060 










$ s3 & 










[3} 3062 










s2 ready 










s3 ready 










$ gv_stat 










Name 


Type 


Value 


Allocated 


Protector 


synch 


int 


0 


3 


CONSOLE 


$ gv_unprotect 


synch 








$ gv_Btat 










Name 


Type 


Value 


Allocated 


Protector 


synch 


int 


3 


3 


NONE 



SEE ALSO Gv_protect, Gv_unprotect, gv_unprotect 
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FUNCTION 



Gv_protect 



SYNTAX 



void Gv__protect (name) 
char *name; 



DESCRIPTION Parameters 

name The name of the global variable 

Comments 

The Gv_protect () function prevents access to the specified variable 
by other EMPOWER/CS scripts. Only the script executing the 
Gv_protect { ) function can access the variable. Other scripts trying to 
access a protected variable will pause until the variable has been 
unprotected You can insert this function into your script when editing 
the script file. 

An error will result if the Gv_protect{) function is executed for a 
variable that does not exist or to which access has not been allocated. 
Also, an error will result if the script attempts to protect a variable which 
it already has protected 

RETURN VALUE (not applicable) 

EXAMPLES The following example demonstrates that the global variable users 

is protected, tested, and then unprotected. 



Gv_alloc { "users " , " int" ) 

Gv_protect("users") ; 

if (Gv_test< "users" , "== 

Gv_write ( "users " , 0) ; 
Gv_unprotect { "users" ) ; 
Gv_inc ( " users " ) ; 



3) ) 



SEE ALSO 



Gv_unprotect, gv_protect, gv_unprotect 
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COMMAND 

SYNTAX 

DESCRIPTION 



gv_read 



gv_read name 



The gv_read command is entered at the shell prompt and returns the 
current value of the specified variable to the standard output 
destination. 



RETURN CODE 



If the command succeeds, the return code is set to zero. If an error 
occurs, the return code is set to one and an error message is sent to the 
standard error destination. 



EXAMPLES In this example the gv„read command returns a current value of 3 

for the variable users: 



$ gv_read users 



SEE ALSO 



Gv read 
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FUNCTION Gv_read, Gv_readv 

SYNTAX int Gv_read (name) 

char *name; 

int Gv_readv (name, value) 
char *name; 



DESCRIPTION Parameters 

name The name of the global variable 

value Where the value of the global variable is stored after it was 
read (for Gv_readv { ) ) 

Comments 

The Gv.read ( ) function returns the current value of the specified 
variable. The Gv_read ( ) function assumes the variable is an integer. If 
the variable is not an integer, the Gv_ready ( ) function should be used 
The Gv_readv ( ) function reads the value specified by the parameter 
name and stores it in the variable specified by the parameter value. 



RETURN VALUE 



The Gv_read ( ) function returns the current value of the specified 
global variable. This value should be stored in a local variable. If the type 
of the variable read is not int, the current value of the variable is 
returned cast as an integer. If an error occurs, the script exits and an 
error message is sent to the standard error destination. 



EXAMPLES If you want a script to read the current value of a global variable called 

balance and the value is an integer, use the Gv_read ( ) function in the 
following script file entries. In this example, the Gv__read() function 
stores the current value of the variable balance in the variable 
curbalance: 
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int curbalance; 

Gv_alloc ("balance", "int") ; 

curbalance = Gv_read { "balance ") ; 



If the value of balance is not an integer, use the Gv__readv ( ) function 
as in the following script file entries: 



float curbalance; 

Gv_alloc ( "balance" , "float") ; 

Gv_readv { " balance " , &curbalance ) ; 



In the above example, the Gv_readv() function retrieves the current 
value of the variable balance and stores it in the floating point variable 
curbalance. 

gv_read 



. 3s 



SEE ALSO 
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COMMAND 



gv_rm 



SYNTAX 
DESCRIPTION 



gv_rm [-f] [-r 



namel name 2 



] 



RETURN CODE 



The gv_rm command is entered at the shell prompt and removes the 
specified variables from shared memory. If a variable currently is 
allocated to a script, the command will fail. If the -f option is used, each 
variable will be removed even if it is allocated to a script. If the - f 
option is used to remove a variable allocated to a script, a warning 
message will appear on screen and the variable will be removed. The 
script will exit the next time it attempts to use the variable. The -r 
option removes all global variables. 

If the command succeeds, the return code is set to zero. If an error 
occurs, the return code is set to one and an error message is sent to the 
standard error destination. 



EXAMPLES The following example command will remove the variables users and 

transactions: 



SEE ALSO 



$ gv_rm users transactions 



gv_seg 
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COMMAND 

SYNTAX 

DESCRIPTION 



RETURN CODE 



gv_rshift 

gv_rshift name value 

The gv_rshif t command is entered at the shell prompt and updates 
the value of a specified variable by performing a bit-wise shift to the 
right on the variable. The parameter value is the operand for the 
operation. When this command is entered, the original value is written 
to the standard output destination before the new value, based on 
operation results, is assigned. 

This command operates on all variable types except strings. 

If the command succeeds, the return code is set to zero. If an error 
occurs, the return code is set to one and an error message is sent to the 
standard error destination. 



SEE ALSO 



Gv_rshift, Gvjshift, gvjshift 
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FUNCTION Gv_rshift, Gv_rshiftv 

SYNTAX int Gv_rshif t (name, value) 

char *name; 
int value; 

int Gv__rshif tv(name, value, oldvalue) 
char *name; 

DESCRIPTION Parameters 

name The name of the global variable 

value The operand for the operation 

oldvalue The pointer location where the original value should be 
stored (for Gv_rshif tv ( ) ) 

Comments 

The Gv_rshif t ( ) and Gv_rshif tv( ) functions update the value of a 
specified variable by performing a bit-wise shift to the right on the 
variable. You can insert these functions irlto your script when editing 
the script file. 

Gv_rshif t ( ) is used if the variable is an integer, and Gv„rshif tv{ ) is 
used if the variable is not an integer 



RETURN VALUE 



Gv_rshif t ( ) returns the original value of the specified variable and 
Gv_rshiftv{) copies the original value to a pointer location. After the 
value of the variable has been updated, the original value, cast as an 
integer, is returned. If an error occurs, the script exits and an error 
message is sent to the standard error destination. 



SEE ALSO Gvjshift, Gv Ishiftv 
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COMMAND gv_seg 

SYNTAX gv_seg [number-of-variables | -r] 

DESCRIPTION The gv„seg command is entered at the shell prompt and creates a 

shared memory segment to support 128 global variables by default. 
When creating a new shared memory segment, the number-of- 
variables argument defines the number of variables the new segment 
will support. The -r option removes the existing shared memory 
segment which removes all existing global variables. If you want to 
create a new shared memory segment with a different size, the existing 
shared memory segment must be removed first 



RETURN CODE 



If the command succeeds, the return code is set to zero. If an error 
occurs, the return code is set to one and an error message is sent to 
the standard error destination. 



EXAMPLES To create a shared memory segment that supports 150 global 

variables, use the following command (assuming a shared memory 
segment does not already exist): 

$ ffv_seg 150 

If a shared memory segment already exists, as would be the case if a 
Global Variables Command had already been executed, the existing 
shared memory segment must be removed before the new segment is 
created: 

$ gv_seg -r 
$ gv_seg 150 



SEE ALSO 



gv_jnit, gv_rm 
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COMMAND gv_setparallel 

SYNTAX gv_set parallel name value 

DESCRIPTION The gv__setparallel command is entered at the shell prompt and 

assigns a new value to the specified parallel variable The new value is 
provided as the second parameter. When the gv.setparallel 
command is entered, the original value is written to the standard output 
destination before the new value is assigned 



RETURN CODE 



If the command succeeds, the return code is set to zero. If an error 
occurs, the return code is set to one and an error message is sent to the 
standard error destination. 



EXAMPLES In the following example, the parallel variable users has a current value 

of 50 and is reassigned a value of 60: 



$ gv_setparallel ^users 60 

50 

$ gv__getparallol users 

60 



SEE ALSO Gv_getparallel, Gv_parallel, Gv_setparallel, Gv_unparallel, 

gv_getparallel, gv_parallel, gv_unparallel 
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FUNCTION 



Gv_setparallel 



SYNTAX 



void Gv_setparal lei (name, value) 
char *name; 

unsigned short int value; 



Parameters 

name The name of the parallel global variable 
value The new value of the specified parallel variable 
Comments 

The Gv_setparallel ( ) function assigns a new value to the specified 
parallel variable. The new value is listed as the second parameter. You 
can insert this function into your script when editing your script file. 

RETURN CODE If the function succeeds, the return code is set to zero. If an error 
occurs, the script exits and an error message is sent to the standard 
error destination. 

SEE ALSO Gv__getparallel, Qv_parallel, Gv_unparallel, gv_getparallel, gv_parallel, 

gv_setparallel, gv_unparallel 



DESCRIPTION 
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COMMAND gv_stat 

SYNTAX gv_stat (name | -s] 

DESCRIPTION The gv_stat command is entered at the shell prompt and returns 

status information to the standard output destination for all variables or 
for a specified variable. The parameter is either a variable name or M -s". 
If the parameter provides the name of a variable, status information is 
provided for that variable only. If the -s option is specified, summary 
information is provided indicating the number of global variables that 
exist compared to the number of variables possible. 

If the command succeeds, the return code is set to zero. If an error 
occurs, the return code is set to one and an error message is sent to 
the standard error destination. 

The gv_stat command sends to the standard output destination a 
table showing the name, type, and value of the specified variable, with 
the number of scripts that have allocated the variable and the identity of 
the variable's protector, if applicable. For example: 



$ gv_stat users 

Name Type Value Allocated Protector 

users int 3 0 NONE 



If gv__stat is executed without an argument, information will be listed for 
all variables: 



$ gv_stat 

Name 


Type 


Value 




Allocated 


Protector 


users 


int 




3 


0 


NONE 


a 


int 




-1 


0 


NONE 


b 


int 




100 


0 


NONE 



RETURN CODE 



EXAMPLES 
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An example using the -s option of gv_stat follows: 



$ gv_stat -s 

10/20 global variables exist 



SEE ALSO Gvstat 
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FUNCTION Gv_stat 

SYNTAX int Gv_stat (name, info) 

char *name; 
struct gv_info *info; 

DESCRIPTION Parameters 

name The name of the global variable 

info The structure where status information for the specified 
global variable is stored 

Comments 

The Gv_stat() function copies the following global variable 
information into a structure specified in the second parameter: current 
value, name, type, owner name, owner process ID, and the number of 
scripts allocated to the variable. You can insert this function into your 
script when editing the script file. 



The gv_info structure is declared in the empowerGV.h file and is 
included automatically in your script by the EMPOWER/CS tool Cscc 
This structure is demonstrated below: 



struct gv_info { 






int index; /* >= 0 indicates allocated to this 


script 


*/ 


int owner; /* >= 0 indicates pid of protecting 


owner * 


/ 


int users; /* number of users allocated */ 






char name [SHMAXNAMELEN] ; 






char type [SHMAXTYPELEN] ; 






union val { 






int i; 






char c; 






.... . ; 

} value; /* current variable value */ 






}; 
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The specified global variable does not need to be allocated to the script 
before executing Gv_stat ( ) . If the variable is not allocated to the script, 
the value of the gv_inf o->index field will be -1 and the gv_info- 
>value field will be empty. 

If the specified variable is protected by another script, the gv_inf o- 
>value field will be empty. The gv_info->owner field will contain the 
process ID of the protecting script. 

The Gv_stat { ) function stores status information for the specified 
global variable in the specified structure. If this process is successful, 
the return code is set to one. If an error occurs, the script exits and an 
error message is sent to the standard error destination. 

The following example demonstrates using Gv_stat ( ) in a script 



struct gv__info info; 

if( Gv_s tat {"users", fcinfo) ) { 

if { strcmpC'int" , info, type) ) { 

fprintf (stderr , "wrong type for global variable 
users: %s\n" , info. type); 
Exit (-1) ; 

} 

} 

else 

Gv_alloc ( "users " , "int", 0) ; 
Beginscenario ( "manager" ) ; 
Endscenario ( "manager" ) ; 



SEE ALSO gv_stat 



RETURN VALUE 



EXAMPLES 



EMPOWER/CS-Vl.0.1 



2-164 

CopyngW PERFORMIX, Inc. © 1 995 



User's Guide— Reference 



COMMAND 



gv_sub 



SYNTAX gv_sub name value 

DESCRIPTION The gv_sub command is entered at the shell prompt and updates the 

value of a specified variable by subtracting the specified amount from 
the variable's current value. The parameter value is the operand for the 
operation. When this command is entered, the original value is written 
to the standard output destination before the new value, based on 
operation results, is assigned. 

This command operates on all variable types except strings. 



RETURN CODE 



If the command succeeds, the return code is set to zero. If an error 
occurs, the return code is set to one and an error message is sent to the 
standard error destination. 



EXAMPLES In the following example, each of the GV commands returns the 

current value of the variable to the standard output destination before 
performing the specified operation. Suppose the variable users has a 
current value of 5 and you wish to make the value 6, then change the 
value by subtracting 4. The interaction would be as follows: 



$ gv_write users 6 

5 

$ gv_sub users 4 

5 

$ gv_read users 

2 



SEE ALSO 



Gv sub 
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FUNCTION 



Gvsub, Gv„subv 



SYNTAX 



in t Gv_s ub ( name , value) 
char *name; 
int value ; 



int Gv_subv (name, value, oldvalue) 
char *name; 

DESCRIPTION Parameters 

name The name of the global variable 

value The operand for the operation 

oldvalue The pointer location where the original value should be 
stored (for Gv_subv { ) ) 

Comments 

The Gv__sub() and Gv_subv() functions update the value of a 
specified variable by subtracting a specified amount from the current 
value of the variable. You can insert these functions into your script 
when editing the script file. 

Gv_sub ( ) is used if the variable is an integer, and Gv_subv ( ) is used if 
the variable is not an integer. The parameter value is the operand for 
the operation, and the parameter oldvalue (for functions ending in V) 
specifies the pointer location where the original value should be stored. 



RETURN VALUE 



Gv_sub ( ) returns the original value of the specified variable and 
Gv_subv ( ) copies the original value to a pointer location. After the 
value of the variable has been updated, the original value, cast as an 
integer, is returned. If an error occurs, the script exits and an error 
message is sent to the standard error destination. 



SEE ALSO 



gv__sub 
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COMMAND 

SYMTAX 

DESCRIPTION 



RETURN CODE 



gv__test 

gv_test name relation-string [value] 

The gv_test command is entered at the shell prompt and compares 
the current value of the specified variable to the specified parameter 
value according to the test relation given in the parameter relation- 
string. If the relation string is a logical comparison ("$" or V), the 
value argument will be ignored. 

If the relational comparison is true, the return code is set to zero and a 
T is written to the standard output destination. If the relational 
comparison is false, the return code is set to one and a "0" is written to 
the standard output destination. If an error occurs, the return code is set 
to two and an error message is sent to the standard error destination. 



EXAMPLES In the following example, the variable users will be tested to 

determine if its value is equal to 2: 



$ 


gv_read 


users 


2 






$ 


gv_test 


users "r==" 2 


1 







Notice that 1 is written to the standard output because the relational 
comparison was true. 

The following example demonstrates both true and false relational 
comparisons: 
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$ gv_init a int 5 

$ gv_test a "<" 1 

0 

$ gv_test a "> n 1 

1 



SEE ALSO Gv test 
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FUNCTION 



Gv test 



SYNTAX 



int Gv_test (name, op, value) 
char *name; 
char *op; 



DESCRIPTION Parameters 

name The name of the global variable 

op The relational test 

value The value to which the variable is compared 
Comments 

The Gv_test { ) function performs a relational comparison between the 
specified variable and the test value, according to the specified test 
relation. You can insert this function into your script when editing the 
script file. 

The type of the global variable tested must match the type of the 
specified comparison value (the value parameter). 

RETURN VALUE If the relational test is true, the return value is set to one. If the test is 
false, the return value is set to zero. If an error occurs, the script exits 
and an error message is sent to the standard error destination. 

EXAMPLES In the following example, the function Gv_test { ) will test the variable 

quit flag to determine if its value is equal to 1. If the comparison is 
true, the script will exit 



Gv_alloc(" quit flag", "int") ; 
if (Gv__test{"quitflag" , ,, ==" , 1) ) 
Exit (1) ; 



SEE ALSO 



gv_test 
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COMMAND 

SYNTAX 

DESCRIPTION 



RETURN CODE 



gv_unparallel 

gv_unparallel name 

The gv_unparallel command is entered at the shell prompt and 
increments the value of the variable by one. When used in conjunction 
with gv_parallel, the parallel variable becomes an "on/off" switch to 
control multiple script execution. 

If the command succeeds, the return code is set to zero. If an error 
occurs, the return code is set to one and an error message is sent to the 
standard error destination. 



SEE ALSO Gv qetparallel, Gv__parallel, Gv_setparallel, Gvjjnparallel, 

qv qetparallel, gv__parallel, gv_setparallel 
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Gv_unparallel 

void Gv_unparal lei (name) 
char *name; 

Parameter 

name The name of the global variable 
Comments 

The Gv_unparallel { ) function increments the value of the variable by 
one. When used in conjunction with the Gv_parallel () function, the 
parallel variable acts as an "on/off" switch to control multiple script 
execution. 

You can insert this function into your script when editing the script file. 

J3 RETURN CODE If the function succeeds, the return code is set to zero. If an error 

occurs, the script exits and an error message is sent to the standard 
J error destination. 

O SEE ALSO Gv_getparallel, Gv_parallel, Gv_setparallel, gv_getparallel, gv_parallel, 

]X gv_setparallel, gv_unparallel 



FUNCTION 
SYNTAX 

DESCRIPTION 
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COMMAND 

SYNTAX 

DESCRIPTION 



RETURN CODE 



gv_unprotect 

gv_unprotect [-f] name ■ 

The gv_unprotect command is entered at the shell prompt and 
removes protection from the specified variable, allowing access to the 
variable by other users and scripts. Only the user that protected a 
variable may unprotect it, unless the -f option is used. The -f option 
forces removal of protection for the variable even if the variable was 
protected by another user or by a script. If the -f option is used, a 
warning message will be returned. This option typically is used when a 
script protecting a variable terminates abnormally. 

If the command succeeds, the return code is set to zero. If an error 
occurs, the return code is set to one and an error message is sent to 
the standard error destination. 



SEE ALSO 



Gv_protect, Gv_unprotect, gv__protect 
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FUNCTION Gv„unprotect 

SYNTAX void Gv_unprotect (name) 

char *name ; 

DESCRIPTION Parameters 

name The name of the global variable 

Comments 

The Gv_unprotect { ) function removes protection from a specified 
variable, allowing other scripts to access the variable. Only the script that 
protected a variable may unprotect it. A variable that has been protected 
by a script may be unprotected at the UNIX script driver with the 
gv_unprotect command if the -f option is used. 

An error will result if the Gv_unprotect ( ) function is executed for a 
variable which does not exist or to which access has not been allocated. 
Also, an error will result if the script attempts to unprotect a variable 
which the script has not protected. 

You can insert this function into your script when editing the script file. 
RETURN VALUE (not applicable) 

EXAMPLES The following example demonstrates that the global variable users 

is protected, tested, and then unprotected. 



Gv_alloc ( "users" , "int" ) ; 

Gv_protect { "users" ) ; 

if (Gv_test{ "users" , "==", 3)) 

Gv_write ( "users " , 0 ) ; 
Gv_unprotect ( "users " ) ; 
Gv_inc ( " users " ) ; 



SEE ALSO Gv_protect, gv_protect, gv_unprotect 
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COMMAND 

SYNTAX 

DESCRIPTION 



RETURN CODE 



gv_waituntil 

gv_waituntil name relation-string [value] 

The gv_waituntil command is entered at the shell prompt and 
compares the current value of the specified variable to the specified 
parameter value according to the test relation given in the parameter 
relation- string. Operations executing the command from the UNIX 
script driver or shell script will pause until the relational comparison is 
true. If the relation string is a logical comparison ("$" or V), the value 
argument will be ignored. 

When the relational comparison becomes true, the return code is set 
to zero. If an error occurs, the return code is set to one and an error 
message is sent to the standard error destination. 



SEE ALSO 



Gv_waituntil, Gv_waitwhile t gv_waitwhile 
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FUNCTION 



Gv waituntil 



SYNTAX 



void Gv_wa it until (name, op, value) 
char *name; 
char *op; 



DESCRIPTION Parameters 

name The name of the global variable 

op The test relation 

value The value that the variable is compared to 
Comments 

The Gv_waituntil ( ) function compares the current value of the 
specified variable to the specified parameter value according to the 
test relation given in the parameter op. Script execution pauses until the 
relational comparison is true. You can insert this function into your 
script when editing the script file. 

EMPOWER/CS executes the specified comparison immediately when 
the Gv_waituntil function is encountered, and again each time the 
value of the global variable has been updated. If the Gv_waituntil ( ) 
function is executed for a global variable which the script has already 
protected, an error will result 



RETURN VALUE 



When the relational comparison becomes true, the return code is set 
to zero. If an error occurs, the script exits and an error message is sent 
to the standard error destination. 



EXAMPLES In the following example, the Gv_waituntil { ) function makes the 

script wait until the value of the variable users is equal to 128: 
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Gv_alloc ( "users " , " int " ) ; 
Gv_inc ( "users" ) ; 

Gv_waituntil ( "users" , "==", 128); 



SEE ALSO Gv_waitwhile, gv_waituntil, gv_waitwhile 
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COMMAND 

SYNTAX 

DESCRIPTION 



RETURN CODE 



gv_waitwhile 

gv_wa it while name relation-string [value] 

The gv_waitwhile command is entered at the shell prompt and 
compares the current value of the specified variable to the specified 
parameter value according to the test relation given in the parameter 
relation-string. Operations executing the command at the UNIX 
script driver or shell script will pause while the relational comparison is 
true. If the relation string is a logical comparison ("$" or "!"), the value 
argument will be ignored. 

When the relational comparison becomes false, the return code is set 
to zero. If an error occurs, the return code is set to one and an error 
message is sent to the standard error destination. 



SEE ALSO 



Gv_waitwhile, Gv_waituntil, gv_waituntil 
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FUNCTION 



Gv waitwhile 



SYNTAX 



void Gvjwait while (name, op, value) 



char *name; 



char *op; 



DESCRIPTION 



Parameters 



name 



The name of the global variable 



op 



The test relation used for the comparison 



value The value that the variable is compared to 
Comments 

The Gv_waitwhile ( ) function compares the current value of the 
specified variable to the specified parameter value according to the 
test relation given in the parameter op. Script execution pauses while 
the relational comparison is true. You can insert this function into your 
script when editing the script file. 

EMPOWER executes the specified comparison immediately when the 
Gv_waitwhile ( ) function is encountered, and again each time the 
value of the global variable has been updated. If the Gv_waitwhile ( ) 
function is executed for a global variable which the script has already 
protected, an error will result 



RETURN VALUE When the relational comparison becomes true, the return code is set 

to zero. If an error occurs, the script exits and an error message is sent 
to the standard error destination. 



script wait while the value of the variable count is less than 20: 



EXAMPLES 



In the following example, the Gv__waitwhile ( ) function makes the 
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Gv_alloc ( "count" , "int"); 

Gv_inc ( "count" ) ; 

Gv_waitwhile ( "count" , " <" , 20 ) ; 



SEE ALSO Gv_waituntil, gv_waituntil, gv_waitwhile 
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COMMAND 

SYNTAX 

DESCRIPTION 



RETURN CODE 



EXAMPLES 



gv_write 

gv_write name value 

The gv_write command is entered at the shell prompt and assigns a 
new value to the specified variable. When the gv_write command is 
entered, the original value is written to the standard output destination 
before the new value is assigned. 

If the command succeeds, the return code is set to zero. If an error 
occurs, the return code is set to one and an error message is sent to the 
standard error destination. 

In the following example, suppose the variable users has a current 
value of 5 and you want to make the value 6. You would enter the 
following command and the current value of the variable would be 
returned: 



$ gv_wxite users 

5 



Then you would enter the gv_read command to see the changed value: 



$ gv_read users 



SEE ALSO 



If the variable type is string and the value specifies to contain spaces, 
you should enclose the value in quotes. For example: 

$ gv_write solution "world peace" 

Gv write 
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FUNCTION Gv_write, Gv_writev 

SYNTAX int Gv_write {name, value) 

char *name; 
int value; 

int Gv__writev (name, value, oldvalue) 
char *name ; 

DESCRIPTION Parameters 

name The name of the global variable 

value The new value assigned to the variable 

oldvalue The pointer location into which the original value should be 
stored 

Comments 

The Gv_write ( ) and Gv_writev{ ) functions assign a new value to the 
specified variable. Gv_write( ) is used if the variable is an integer, and 
Gv_writev() is used if the variable is not an integer. The value 
parameter specifies the new value. In the Gv_writev() function, the 
oldvalue parameter specifies the pointer location into which the 
original value should be stored. 

You can enter these functions into your script when editing the script 
file. 



RETURN VALUE 



The Gv_write ( ) function returns the original value of the specified 
variable and the Gv_writev() function copies the original value to a 
pointer location. After the new value has been assigned to the variable, 
the original value, cast as an integer, is returned. If an error occurs, the 
script exits and an error message is sent to the standard error 
destination. 



EMPOWER/CS-Vl.0.1 



2-182 

Copyright PERFORMIX, Inc. © 1995 



User's Guide— Reference 



EXAMPLES To assign a new value to the variable with the name count, use the 

following example if count is an integer; 



Gv_alloc { "count" , "int") ; 
Gv_write{ "count" , 12) ; 



To assign a new value to the non-integer variable balance, use: 



float curbalance; 




Gv_alloc { "balance" , 


"float") ; 


Gv_writev ( "balance" 


, 120.75, fccurbalance) ; 



SEE ALSO gv_write 
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COMMAND 



gv_xor 



SYNTAX 
DESCRIPTION 



RETURN CODE 



gv_xor name value 

The gv__xor command is entered at the shell prompt and updates the 
value of a specified variable by applying a bit-wise EXCLUSIVE-OR 
masking to a variable. The parameter value is the operand for the 
operation. When this command is entered, the original value is written 
to the standard output destination before the new value, based on 
operation results, is assigned. 

This command operates on all variable types except strings. 

If the command succeeds, the return code is set to zero. If an error 
occurs, the return code is set to one and an error message is sent to 
the standard error destination. 



SEE ALSO 



Gv xor 
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FUNCTION Gv_xor, Gv_xorv 

SYNTAX int Gv_xor (name, value) 

char *name; 
int value; 

int Gv_xorv(name, value, oldvalue) 
char *name; 

DESCRIPTION Parameters 

name The name of the global variable 

value The operand for the operation 

oldvalue The pointer location where the original value should be 
stored 

Comments 

The Gv_xor() and Gv_xorv() functions update the value of a 
specified variable by applying a bit-wise EXCLUSIVE-OR masking to a 
variable. You can insert these functions into your script when editing 
your script file. 

Gv_xor { ) is used if the variable is an integer, and Gv__xorv { ) is used if 
the variable is not an integer. The parameter value is the operand for 
the operation, and the parameter oldvalue (for Gv_xorv()) specifies 
the pointer location where the original value should be stored. 



RETURN VALUE 



Gv_xor ( ) returns the original value of the specified variable and 
Gv_xorv ( ) copies the original value to a pointer location. After the 
value of the variable has been updated, the original value, cast as an 
integer, is returned. If an error occurs, the script exits and an error 
message is sent to the standard error destination. 



SEE ALSO 



gv_xor 
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FUNCTION 



Hostname 



SYNTAX 



Hostname ( lognum, hostname) 
int lognum; 
char * hostname ; 



DESCRIPTION Parameters 

lognum An identifier of a logon communication structure 



hostname The name of the host machine that includes the database 
server 

Comments 

This function is inserted into the script to inform the LogonQ 
connection on which machine the database(s) and server reside. It will 
occur in the script before a Logon { ) function. 

During script execution, the Hostname () function is used in the 
process to access the SUT by specifying the name of the host machine 
where the database server being tested resides. 

Note: Because this function is inserted into your script based on how 
the client application interacts with the SUT, you should not attempt to 
edit this function or remove it from the script. If you change this 
function from when it was captured in the script file, you may drastically 
alter the expected behavior of the application and SUT and therefore, 
break your script during execution. 



RETURN VALUE If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 



Hostname (LOGl, "SUT"); /* the DBserver resides on machine name SUT */ 



EXAMPLE 



The following example demonstrates this function used in a script 



SEE ALSO 



AppName, Language, Password, Servername, Username 
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FUNCTION 



InitialWindow 



SYNTAX 



InitialWindow (task, window, x, y, width, height) 

int task; 

char * window ; 

int x,y, width, height; 



DESCRIPTION 



Parameters 
task 



The order of the open program as a task 



window 



The title of the open window 



The on screen x,y coordinates of the top, left corner of the 
window 



width The width and height of the window on screen 
height 

Comments 

This function is an EMPOWER/CS function that is inserted into the 
script during Capture after the BeginscenarioO function. 
InitialWindow ( } records the state of your Windows desktop by 
listing all active program windows at the time the Capture session 
began. Therefore, multiple InitialWindow ( ) functions can be 
recorded into the script and are listed consecutively. 

The first parameter, task, indicates the order of the specified program 
in the MS Windows task list The position in the task list is important 
for users who capture using "Fast-Tab" task switching. A task 
parameter of zero is a reserved value that records the screen resolution 
during Capture and verifies the resolution during script execution in 
Display mode. 

The window parameter identifies the title of the window. The x,y 
parameters indicate the top left x,y coordinates of the window's position 
on screen. The width and height parameters determine the size of the 
window as displayed. If width and height are both zero, the window is 
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minimized If the x,y parameters are both zero and width is maxwidth 
and height is maxheight, the window is maximized, [f neither of these 
conditions apply, the window is in a normal state. 

During script execution in Display mode, initialwindow() attempts to 
locate the Windows listed as its parameters and place them in the same 
positions as captured. The function does not apply to Non-Display mode 
script execution. 

If the specified programs are not open during script execution, the log 
file will record an error but script execution will continue. Therefore, 
before you execute your script in Display mode, your desktop should 
be in the same state with the same applications open as when you 
captured the script 

Note: You should not attempt to remove or edit this function in your 
script file because you change the state of the windows desktop as it 
was captured, and, therefore run the risk of breaking the script. 

RETURN VALUE If the function is successful, zero is returned If an error occurs, -1 is 
returned 

EXAMPLES The following example demonstrates initialwindowO in a script 

file: 



InitialWindow(0, "Desktop" , 0, 0, 640,480) ; /* Screen resolution */ 

InitialWindowCl, "MS-DOS Prompt" ,21 , 408,0, 0) ; /* Minimized window */ 

InitialWindow(2, "File Manager" , 0, 0 , MAXWIDTH, MAXHEIGHT) ; /* Maximized window */ 
InitialWindow (3, "Program Manager" , 36,26, 545, 333) ; /* Normal window */ 



The following example demonstrates the log file of an executed script 
that encountered an error because the desktop was not restored to its 
captured state: 
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InitialWindow(2 , "File Manager ",0,0, MAXWIDTH , MAXHEIGHT ) 
Warning: Unable to find window 



SEE ALSO CurrentWindow 
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FUNCTION 
SYNTAX 



Inote 

Inote (n) 
int n; 



DESCRIPTION Parameters 

n An integer to be displayed in Monitor 

Comments 

The inote ( ) function specifies a message that will appear in the "Mote" 
column of Monitor View 5. The n parameter is an integer that will be 
displayed. When a script is executed with the inote ( ) function, an 
inote ( ) statement is placed into the scripts log file. 

You must insert the inote ( ) function into the script when editing your 
script file. 

RETURN VALUE If the function is successful, zero is returned. If an error occurs, -1 is 
returned 
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EXAMPLES The following example demonstrates using inote ( ) in a script to 

identify the number of a loop as it executes: 



for (i=l; i<10; i++){ 

Inote(i); /* identify loop number */ 



} 



SEE ALSO 



Note 
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FUNCTION 



KeyDown 



SYNTAX 



void KeyDown (key) 
unsigned int key; 



DESCRIPTION Parameters 

key A Microsoft Windows virtual key code value 

Comments 

The KeyDown ( ) function is inserted in the script file automatically 
during Capture when the user presses the specified key. During script 
execution in Display mode, this function is used to emulate pressing the 
specified key down. In Non-Display mode, this function is used to 
emulate the type delay for pressing the key. 

The parameter key represents a Microsoft Windows virtual key code 
value. Some examples of valid virtual key codes are vk_space, 

VK_DELETE, VK_BACK, VK_DOWN, VK_UP, and VKJESCAPE. 

The KeyDown ( ) function may be edited in your script file, but because 
you change the activity as it was captured, you run the risk of breaking 
the script. If you edit a KeyDown ( ) function, you also must edit the 
associated KeyUp ( ) function. 

RETURN VALUE (not applicable) 



EXAMPLES The following example demonstrates various key events where the 

user pressed the left arrow key, the shift key, the tab key, control key, 
and escape key: 
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WindowRcv ( 11 Pt " ) ; 
KeyPress (VK_LEFT) ; 
KeyDown (VK__SHIFT) ; 
KeyPress (VK_TAB) ; 
KeyUp(VK_SHIFT) ; 
KeyDown (VK_CONTROL) ; 

Type( ,,A I A r) ; 

KeyUp (VK_CONTROL) ; 

KeyPress (VK_ESCAPE) ; 



SEE ALSO KeyPress, KeyUp, SysKeyDown, SysKeyPress, SysKeyUp 
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FUNCTION 



KeyPress 



SYNTAX 



void KeyPress (key) 
unsigned int key; 



DESCRIPTION Parameters 

key A Microsoft Windows virtual key code value 

Comments 

A KeyPress ( ) function is translated into a down/up key sequence. A 
KeyPress () function is inserted in the script file automatically during 
Capture when no other user events occur between a KeyDown/Up pair. 
If the key is the same for consecutive KeyDown and KeyUp events, the 
key events will automatically be translated into a KeyPress. 

During script execution in Display mode, this function is used to 
emulate the pressing and releasing of the specified key. In Non-Display 
mode, this function is used to emulate the type delay for pressing and 
releasing the key. 

The parameter key represents a Microsoft Windows virtual key code 
value. Some valid virtual key codes are vk_space, vk_delete, 
vk_back, vk_down, and vk_up. 

Key events may be edited within the script file, but because you change 
the activity as it was captured, you run the risk of breaking the script 

RETURN VALUE (not applicable) 



EXAMPLES The following example demonstrates various key events where the 

user pressed the left arrow key, the shift key, the tab key, control key, 
and escape key: 
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WindowRcv( "Pt" ) ; 
KeyPress (VK_LEFT) ; 
KeyDown { VK_SHIFT ) ; 
KeyPress (VK_TAB) ; 
KeyUp(VK_SHIFT) ; 
KeyDown (VK_CONTROL) ; 

Type(" A I A ri M ) ; 

KeyUp CVK_CONTROL) ; 

KeyPress (VK_ESCAPE) ; 



KeyDown, Keytlp, SysKeyDown, SysKeyPress, SysKeyUp 
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FUNCTION 



KeyUp 



SYNTAX 



void KeyUp ( key ) 
unsigned int key; 



DESCRIPTION Parameters 

key A Microsoft Windows virtual key code value 

Comments 

The KeyUp ( ) function is inserted in the script file automatically during 
Capture and indicates that a non-printable keyboard key on the PC was 
released. During script execution in Display mode, this function is used 
to emulate releasing the specified key. In Non-Display mode, this 
function is used to emulate the type delay for releasing the key. 

The parameter key represents a Microsoft Windows virtual key code 
value. Some valid virtual key codes are vk_space, vk_delete, 
vk_back, vk_down, and VK_UP. 

This function may be edited within your script file, but because you 
change the activity as it was captured, you run the risk of breaking the 
script. If you edit the KeyUp { ) function, you also must edit the 
associated KeyDown ( ) function. 

RETURN VALUE (not applicable) 



EXAMPLES The following example demonstrates various key events where the 

user pressed the left arrow key, the shift key, the tab key, control key, 
and escape key: 
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WindowRcv ( " Pt " ) ; 
KeyPress (VK_LEFT) ; 
KeyDown (VK_SHIFT) ; 
KeyPress (VK_TAB) ; 
KeyUp(VK__SHIFT) ; 
KeyDown (VK_CONTROL) ; 

Type(" A I"I~I") ; 

KeyUp(VK_CONTROL) ; 

KeyPress (VK_ESCAPE) ; 



KeyDown, KeyPress, SysKeyDown, SysKeyPress, SysKeyUp 
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FUNCTION 



LeftButtonDown 



SYNTAX 



void Left But tonDown (x, y) 
unsigned int x,y; 



DESCRIPTION 



Parameters 



x The on screen x coordinate of the PC mouse 
y The on screen y coordinate of the PC mouse 

Comments 

The LeftButtonDown ( ) function is inserted in the script file 
automatically during Capture when the user depresses the left mouse 



button. During script execution in Display mode, this function is used to 
emulate pressing the left mouse button down. In Non-Display mode, this 
function is used to emulate the pointer rate delay based on the x,y 
parameters. 



The x,y parameters indicate the position of the mouse on screen at the 
time the button was pressed during Capture. 

The Lef tButtonDown( ) function may be edited in your script file, but 
because you change the activity as it was captured, you run the risk of 
breaking the script 



RETURN VALUE (not applicable) 



EXAMPLES 



The following example demonstrates various left button activities: 



AppWait (5.21) ; 
WindowRcv("Pt") ; 



Lef tButtonDown{213, 111) ; 



(continued on following page . 



J 
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AppWait (0.55) ; 
WindowRcv ("Pt") ; 

LeftButtonUp(222, 195) ; 



AppWait (0.38) ; 
WindowRcv ( " Pt " ) ; 

Lef tButtonDown<340, 216) ; 
LeftButtonUp(333,219) ; 

AppWait (0.17) ; 
WindowRcv ( " Pt " ) ; 

LeftButtonPress (338,220) ; 



Sometimes, a comment is inserted by EMPOWER/CS before a button 
event to add context to the script. In this example, the comment 
indicates double clicking a button called tr Fetch. M 



/* Clicked (Button) (FETCH) */ 
LeftDblPress(276 / 345) ; 



SEE ALSO LeftButtonPress, LeftButtonUp, LeftDblPress 
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FUNCTION 



LeftButtonPress 



SYNTAX 



void LeftButtonPress (x, y) 
unsigned int x,y; 



DESCRIPTION Parameters 

x The on screen x coordinate of the PC mouse 



The LeftButtonPress ( } function indicates when the left button on the 
PC mouse was pressed down and released during Capture. A 
LeftButtonPress () function is inserted in the script when no other 
user events occur between a LeftButtonDown/Up pair. If the x,y 
coordinates are the same for consecutive LeftButtonDown and 
LeftButtonUp events, the left mouse button events will be translated into 
a LeftButtonPress ( ) . 

During script execution in Display mode, this function is used to 
emulate pressing and releasing the left mouse button. In Non-Display 
mode, this function is used to emulate the pointer rate delay based on 
the x , y parameters. 

The x,y parameters indicate the position of the mouse on screen at the 
time the button was pressed. 

The LeftButtonPress ( ) function may be edited in your script file, but 
because you change the activity as it was captured, you run the risk of 
breaking the script. 



y The on screen y coordinate of the PC mouse 



Comments 



RETURN VALUE (not applicable) 



EXAMPLES 



The following example demonstrates various left button activities: 
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AppWait (5.21) ; 
WindowRcv( "Pt" ) ; 

LeftButtonDown(213 / 111) ; 



AppWait (0.55) ; 
WindowRcv { " Pt " ) ; 

LeftButtonUp<222, 195) ; 



AppWait (0.38) ; 
WindowRcv ("Pt" ) ; 

LeftButtonDown(340,216) ; 
LeftButtonUp( 333,219) ; 

AppWait (0.17) ; 
WindowRcv ( n Pt H ) ; 

LeftButtonPress{338,220) ; 



Sometimes, a comment is added before a button event to add context to 
the script In this example, the comment indicates double clicking a 
button called 'Fetch." 
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/* Clicked (Button) (FETCH) */ 
Lef tDblPress (276, 345) ; 



SEE ALSO LeftButtonDown, LeftButtonUp, LeftDblPress 
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FUNCTION 



LeftButtonUp 



SYNTAX 



void LeftButtonUp (x,y) 
unsigned int x,y; 



DESCRIPTION Parameters 

x The on screen x coordinate of the PC mouse 



y The on screen y coordinate of the PC mouse 
Comments 

The LeftButtonUp { ) function is inserted in the script file automatically 
during Capture when the user releases the left mouse button. During 
script execution in Display mode, this function is used to emulate 
releasing the left mouse button. In Non-Display mode, this function is 
used to emulate the pointer rate delay based on the x,y parameters. 

The x,y parameters indicate the position of the mouse on screen at the 
time the button was released during Capture. 

The LeftButtonUp { ) function may be edited in your script file, but 
because you change the activity as it was captured, you run the risk of 
breaking the script 



RETURN VALUE (not applicable) 



EXAMPLES 



The following example demonstrates various left button activities: 
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AppWait (5.21) ; 
WindowRcv("Pt" ) ; 

LeftButtonDown(213 / 111) ; 



AppWait (0.55) ; 
WindowRcv( "Pt" ) ; 

LeftButtonUp(222, 195) ; 



AppWait (0.38) ; 
WindowRcv ( " Pt " ) ; 

LeftButtonDown(340,216) ; 
LeftButtonUp(333,219) ; 

AppWait (0.17) ; 
WindowRcv ( " Pt " ) ; 

LeftButtonPress (338,220) ; 



ri Sometimes, a comment is added before a button event to add context to 

fy the script In this example, the comment indicates double clicking a 

01 button called 'Fetch" 



/* Clicked (Button) (FETCH) */ 
LeftDblPress(276,345) ; 



SEE ALSO LeftButtOnDown, LeftButtonPress, LeftDblPress 
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FUNCTION LeftDblPress 

SYNTAX void LeftDblPress (x, y) 

unsigned int x,y; 

DESCRIPTION Parameters 

x The on screen x coordinate of the PC mouse 

y The on screen y coordinate of the PC mouse 
Comments 

The LeftDblPress ( ) function is inserted in the script file automatically 
during Capture to indicate that a double press of the left mouse button 
occurred. During script execution in Display mode, this function is used 
to emulate a double press of the left mouse button down. In Non-Display 
mode, this function is used to emulate the pointer rate delay based on 
the x, y parameters. 

The x,y parameters indicate the position of the mouse on screen at the 
time the button was double-clicked during Capture. 

This function may be edited in your script file, but because you change 
the activity as it was captured, you run the risk of breaking the script 

RETURN VALUE (not applicable) 

EXAMPLES The following example demonstrates various button activities: 



AppWait (5.21) ; 
WindowRcvCPt" ) ; 

LeftDblPress (213, 111) ; 



AppWait (0.55) ; 
WindowRcv{ "Pt" ) ; 



EMPOWER/CS-Vl.0.1 



2-205 

Copyright PERFORMfX, Inc. © 1995 



User's Guide— Reference 



LeftButtonUp(222, 195) ; 



AppWait (0.38) ; 
WindowRcv ( " Pt " ) ; 

Lef tButtonDown(340, 216) ; 
LeftButtonUp{333,219) ; 
LeftButtonPress(338,221) ; 

AppWait (0.17) ; 
WindowRcv ( " Pt " ) ; 



Sometimes, a comment is added before a button event to add context to 
the script In this example, the comment indicates double clicking a 
button called 'Fetch." 



/* Clicked (Button) (FETCH) */ 
LeftDblPress(276,345) ; 



SEE ALSO LeftButtonDown, LeftButtonPress, LeftButtonUp 
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FUNCTION 
SYNTAX 



Log 

void Log (str) 
char *str; 



DESCRIPTION 



Parameters 

str A null-terminated string recorded into the log file of 

executed script 



an 



Comments 

You can insert the Log ( ) function into your script when editing the 
script file. This function allows you to place additional information in a 
log, such as the value of a variable. 

Log ( ) records the parameter str in the log file. The parameter str is a 
null-terminated string and is recorded in the log file in the following 
format 

»> 16 Log ("str") 

Note: The number following the "»>" is the line number corresponding 
to a line in the script file. 



RETURN VALUE (not applicable) 



SEE ALSO 



Inote, Note 
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FUNCTION Logoff 

SYNTAX Logoff (lognum) 

int lognun\; 

DESCRIPTION Parameters 

lognum An identifier of a logon communication structure 

Comments 

The Logoff () function is inserted into the script file when a logon 
structure is closed. A logoff usually occurs when a user terminates a 
connection with the SUT. 

During script execution, this function closes the logon structure that was 
opened with the corresponding Logon ( ) . All active cursors on the 
specified logon structure must be closed before the logon structure will 
close. 

Note: Because this function is inserted into your script based on how 
the client application interacts with the SUT, you should not attempt to 
edit this function or remove it from the script. If you change this 
function from when it was captured in the script file, you may drastically 
alter the expected behavior of the application and SUT and therefore, 
break your script during execution. 

RETURN VALUE If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 

EXAMPLES The following example demonstrates a Logoff ( ) function in a script: 
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Close (CURl) ; 
Logoff (L0G1) ; 
Closenv (ORACLEl) ; 

Endscenario ( " script 1 " ) ; 



Close, Goseenv, Logon 
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FUNCTION Logon 

SYNTAX Logon ( dbnum , 1 ognum ) 

in t dbnum , 1 o gnum ; 

DESCRIPTION Parameters 

dbnum The number of the database environment 

lognum An identifier of a logon communication structure 
Comments 

The Logon () function is inserted into the script when a logon 
connection to the database is opened. During script execution, this 
y function opens a communication link to the database for a particular 

database environment • 

N The database environment for the specified dbnum must have been 

U opened with Openenv { ) before a Logon { ) call will execute. The 

jS Logon ( ) function provides access to the database so that a cursor 

s structure can be opened to process the SQL statement. Therefore, 

^ Logon ( ) will occur after Openenv ( ) and before Open ( ) in the script. 

5t The specifications for Username ( ) and Password ( ) also must be called 

fp in the script before a Logon ( ) function will successfully execute. 

W Opening more than one logon connection from a database environment 

is possible. The first logon structure opened will be numbered by 
EMPOWER/CS as logi, the second as LOG2, etc 

Note: Because this function is inserted into your script based on how 
the client application interacts with the SUT, you should not attempt to 
edit this function or remove it from the script. If you change this 
function from when it was captured in the script file, you may drastically 
alter the expected behavior of the application and SUT and therefore, 
break your script during execution. 
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RETURN VALUE If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 

EXAMPLES The following script segment demonstrates the process of logging on 

to the database, oracle, from the logon structure LOGl: 



Type { " scott A Itiger^ITRAMP A M" ) 




Username(LOGl, " scott@ TRAMP" ) ; 
Password (LOGl , " tiger" ) ; 
Logon { ORACLE , LOGl ) ; 




AppWait (0.05) ; 




Think{2.35) ; 




Open { LOGl , CUR1 ) ; 




Parse {CUR1 # "SELECT EMPNO , ENAME, JOB, 
SAL, COMM, DEPTNO FROM EMP, UPDATE OF 
JOB, MGR, HIREDATE, SAL, COMM, DEPTNO" 


MGR, HIREDATE, 
EMPNO y ENAME, 

); 



SEE ALSO Logoff, Open, Openenv, Password, Username 
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FUNCTION MiddleButtonDown 

SYNTAX void MiddleButtonDown (x,y) 

unsigned int x,y; 



DESCRIPTION Parameters 

x The on screen x coordinate of the PC mouse 

y The on screen y coordinate of the PC mouse 
Comments 

The MiddleButtonDown ( ) function is inserted in the script file 
automatically during Capture when the user depresses the middle 
mouse button. During script execution in Display mode, this function is 
used to emulate pressing the middle mouse button down. In Non- 
Display mode, this function is used to emulate the pointer rate delay 
based on the x,y parameters. 

The x,y parameters indicate the position of the mouse on screen at the 
time the button was pressed 



The MiddleButtonDown! ) function may be edited in your script file, 
but because you change the activity as it was captured, you run the risk 
of breaking the script. If you change the MiddleButtonDown ( ) 
function, you also must change the associated MiddleButtonUp { ) 
function. 



RETURN VALUE (not applicable) 

EXAMPLES The following example demonstrates various button activities: 
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AppWait (5.21) ; 
WindowRcvt "Pt" ) ; 

LeftButtonDown(213 , 111} ; 

AppWait (0.55) ; 
WindowRcvC'Pt" } ; 

Lef tButtonUp<222, 195) ; 



AppWait (0.38) ; 
WindowRcv{ "Pt" ) ; 

MiddleButtonDown(340 / 216) ; 
MiddleButtonUp(333 / 219) ; 
MiddleButtonPress (338,221) ; 

AppWait (0.17) ; 
WindowRcvC'Pt") ; 



Sometimes, a comment is added before a button event to add context to 
the script In this example, the comment indicates double clicking a 
button called Tetch. M 



/* Clicked (Button) (FETCH) */ 
MiddleDblPress (276,345) ; 



SEE ALSO MiddleButtonPress, MiddleButtonUp, MiddleDblPress 
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FUNCTION MiddleButtonPress 

SYNTAX void MiddleButtonPress (x,y) 

unsigned int x,y; 

DESCRIPTION Parameters 

x The on screen x coordinate of the PC mouse 

y The on screen y coordinate of the PC mouse 
Comments 

The MiddleButtonPress ( ) function indicates when the middle button 
on the PC mouse was pressed down and released during Capture. A 
MiddleButtonPress ( ) is inserted in the script when two consecutive 
S[ MiddleButtonDown/Up events do not have any other user events 

between them. 

^ The x,y parameters indicate the position of the mouse on screen at the 

J time the button was pressed during Capture. 

H During script execution in Display mode, this function is used to 

emulate pressing and releasing the middle mouse button. In Non- 
fS Display mode, this function is used to emulate the pointer rate delay 

Q based on the x, y parameters. 

The MiddleButtonPress { ) function may be edited in your script file, 
but because you change the activity as it was captured, you run the risk 
of breaking the script 
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RETURN VALUE (not applicable) 

EXAMPLES The following example demonstrates various button activities: 



AppWait (5.21) ; 
WindowRcv ( "Pt" ) ; 

LeftButtonDown(213,lll) ; 



AppWait (0. 55) ; 
WindowRcv { 11 Pt " ) ; 

LeftButtonUp{222 , 195) ; 



AppWait (0.38) ; 
WindowRcv ( " Pt " ) ; 

MiddleButtonDown(340,216) ; 
MiddleButtonUp(333,219) ; 
MiddleButtonPress (338,221) ; 

AppWait (0.17) ; 
WindowRcv ( "Pt" ) ; 



Sometimes, a comment is added before a button event to add context to 
the script. In this example, the comment indicates double clicking a 
button called 'Fetch" 



/* Clicked (Button) (FETCH) */ 
MiddleDblPress (276,345); 



SEE ALSO MiddleButtonDown, MiddleButtonUp, MiddleDblPress 
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FUNCTION MiddleButtonUp 

SYNTAX void MiddleButtonUp (x,y) 

unsigned int x,y; 

DESCRIPTION Parameters 

x The on screen x coordinate of the PC mouse 

y The on screen y coordinate of the PC mouse 
Comments 

The MiddleButtonUp ( ) function is inserted in the script file 
automatically during Capture when the user releases the middle mouse 
O button. During script execution in Display mode, this function is used to 

^ emulate releasing the middle mouse button. In Non-Display mode, this 

h function is used to emulate the pointer rate delay based on the x , y 

Sj parameters. 

]5 The x, y parameters indicate the position of the mouse on screen at the 

s time the button was released during Capture. 

T: The MiddleButtonUp ( ) function may be edited in your script file, but 

m because you change the activity as it was captured, you run the risk of 

p breaking the script If you edit this function, you also must change the 

W associated MiddleButtonDown( ) function. 

RETURN VALUE (not applicable) 
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EXAMPLES The following example demonstrates various button activities: 



AppWait (5.21) ; 
WindowRcv { " Pt " ) ; 

LeftButtonDown(213, 111) ; 



AppWait (0.55) ; 
WindowRcv ("Pt") ; 

LeftButtonUp(222, 195) ; 



AppWait (0. 38) ; 
WindowRcv { " Pt " ) ; 

MiddleButtonDown(340, 216) ; 
MiddleButtonUp{333,219) ; 
MiddleButtonPress (338,221) ; 

AppWait (0.17) ; 
WindowRcv ("Pt") ; 



Sometimes, a comment is added before a button event to add context to 
the script. In this example, the comment indicates double clicking a 
button called 'Fetch." 



/* Clicked (Button) (FETCH) */ 
MiddleDblPress (276, 345) ; 



SEE ALSO MiddleButtonDown, MiddleButtonPress, MiddleDblPress 
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FUNCTION MiddleDblPress 

SYNTAX void MiddleDblPress (x, y) 

unsigned int x,y; 

DESCRIPTION Parameters 

x The on screen x coordinate of the PC mouse 

y The on screen y coordinate of the PC mouse 
Comments 

The MiddleDblPress { ) function is inserted in the script file 
automatically during Capture to indicate that a double press of the 
O middle mouse button occurred. During script execution in Display 

r£ mode, this function is used to emulate a double press of the middle 

mouse button. In Non-Display mode, this function is used to emulate the 
%l pointer rate delay based on the x,y parameters. 

'% The x,y parameters indicate the position of the mouse on screen at the 

s time the button was double-clicked during Capture. 

y The MiddleDblPress ( ) function may be edited in your script file, but 

ipj because you change the activity as it was captured, you run the risk of 

□ breaking the script 

RETURN VALUE (not applicable) 
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EXAMPLES The following example demonstrates various button activities: 



AppWait{5.21) ; 
WindowRcv { " Pt " ) ; 

LeftButtonDown(213, 111) ; 



AppWait{0.55) ; 
WindowRcv ( "Pt" ) ; 

LeftButtonUp(222, 195) ; 



AppWait (0.38) ; 
WindowRcv ("Pt") ; 

MiddleButtonDown(340,216) ; 
MiddleButtonPress(333,219) ; 
MiddleButtonUp(338, 221) ; 

AppWait (0.17) ; 
WindowRcv ( "Pt" ) ; 



Sometimes, a comment is added before a button event to add context to 
the . script. In this example, the comment indicates double clicking a 
button called Tetch." 



/* Clicked (Button) (FETCH) */ 
MiddleDblPress{276, 345) ; 



SEE ALSO MiddleButtonDown, MiddleButtonPress, MiddleButtonUp 
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FUNCTION 



Note 



SYNTAX 



Note (str) 

unsigned char *str; 



DESCRIPTION Parameters 

str The text of a message to be displayed in Monitor 

Comments 

You must insert the Note( ) function into the script when editing. The 
Noted function specifies a message that will appear in the "Note" 
column of Monitor View 5. The str parameter is the text of the 
message and this message must be contained within double quotes. 
When a script executes, all Note ( ) statement will be listed in the log file. 

RETURN VALUE If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 



SEE ALSO 



Inote, Log 
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FUNCTION 



Open 



SYNTAX 



Open { 1 ognum , curnum ) 
int 1 ognum, curnum; 



DESCRIPTION 



Parameters 



1 ognum An identifier of a logon communication structure 
curnum An identifier of a cursor communication structure 

Comments 

The Open ( ) function is inserted into the script file when a cursor 
communication structure is opened. It is inserted after a Logon ( ) call 
and before database processing begins. 

During script execution, this function enables the script to interact with 
the database over a communication structure called a cursor. A cursor 
structure is opened so that the SQL statement can be processed. The 
OpenO function opens a cursor from the logon connection with the 
database and multiple cursors can be opened for a particular logon 
structure. 

The parameter lognum specifies the logon structure from which the 
cursor was opened. The parameter curnum specifies the cursor on 
which the script will be operating. 

Note: Because this function is inserted into your script based on how 
the client application interacts with the SUT, you should not attempt to 
edit this function or remove it from the script. If you change this 
function from when it was captured in the script file, you may drastically 
alter the expected behavior of the application and SUT and therefore, 
break your script during execution. 



RETURN VALUE If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 
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EXAMPLES The following example script segment demonstrates opening a cursor, 

curi, from the logon structure logI: 



Logon ( 0RACLE1 , LOGI ) ; 
AppWait (0 . 05) ; 
Think (2. 35) ; 

Open (LOGI, CURI) ; 

Parse {CURI , "SELECT EMPNO, ENAME, JOB, MGR, HIREDATE, 
SAL, COMM, DEPTNO FROM EMP, UPDATE OF EMPNO, ENAME, 
JOB, MGR, HIREDATE, SAL, COMM, DEPTNO"); 



Define (CURI, 
Define (CURI, 
Define (CURI, 
Define (CURI, 
Define (CURI, 



n ^ ii 


STRING, 


5) ; 


"2" , 


STRING, 


11) ; 


"3", 


STRING, 


10) ; 


"4" , 


STRING, 


5) ; 


"5", 


STRING, 


10); 


"6", 


STRING, 


9) ; 


« *y ii 


STRING, 


9) ; 


"8" , 


STRING, 


3) ; 



Exec (CURI) ; 

Fetch (CURI) ; 
GetNextRow(CURl) ; 



SEE ALSO 



Close, Logon, Openenv 
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FUNCTION 
SYNTAX 



Openenv 

Openenv {dbnum, v) 
int dbnum, v; 



DESCRIPTION Parameters 

dbnum The number of the database environment 

v The version number of the database 

Comments 

The Openenv ( ) function is inserted into the script when a database 
environment is opened. During script execution, Openenv ( ) opens an 
environment specifying the database and database version to be used 
for the emulation. 

Log on connections to the database can be made only from an open 
environment. 



RETURN VALUE 



In some cases, multiple databases may be accessed and activity for each 
database may occur concurrently. Therefore, more than one Openenv ( ) 
may be captured into a script depending on the captured application 
activity. 

Note: Because this function is inserted into your script based on how 
the client application interacts with the SUT, you should not attempt to 
edit this function or remove it from the script. If you change this 
function from when it was captured in the script file, you may drastically 
alter the expected behavior of the application and SUT and therefore, 
break your script during execution. 

If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 
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EXAMPLES 



The following example demonstrates how Openenv ( ) may appear in a 
script file. In this example, a Version V6V7 Oracle database was 
specified: 



Openenv (ORACLEl, VERSIONV6V7 ) ; 



SEE ALSO 



Closenv, Logon, Open 
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FUNCTION Paceconstant 

SYNTAX Paceconstant {str , n) 

char *str; 
int n; 



DESCRIPTION Parameters 

str An argument naming the pace and defining the speed of the 

pace 

n The number of seconds the script should delay since the last 

call to Paceconstant ( ) 

Comments 

Pacing functions can be inserted into your script file to control the pace 
of the script. These functions cause the script to pause long enough to 
make the script send transactions to the SUT at a predetermined 
throughput Typically used in a loop, these functions may be nested to 
permit controlled throughput of transactions within a larger transaction. 

Paceconstant ( ) causes transactions to be submitted at a constant 
throughput. It accepts an argument naming the pace and defining the 
speed of the pace. The second argument to Paceconstant { ) defines 
the number of seconds that the script should take since the last call to 
Paceconstant ( ). The first call to a pacing function does not delay; it is 
used as a starting point for the subsequent calls. For this reason, the 
first call to a pacing function is often made with arguments of 0 to 
define the speed. 

Note: You are permitted to nest pacing functions in a script. If you do 
so, we recommend setting the starting point for a pace explicitly, i.e. 
with the speed argument of 0. This will ensure that an inner loop 
executed at a fixed pace will begin execution immediately every time 
that the loop begins. 
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RETURN VALUE This function returns the amount of time delayed. 
SEE ALSO Pacetne, Paceuniform 
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FUNCTION 



Pacetne 



SYNTAX 



Pacetne (str, rain, ave, max) 



char *str; 



int min, ave, max; 



DESCRIPTION 



Parameters 



str 



An argument naming the pace and defining the speed of the 
pace 



mm 



An integer specifying minimum delay for the speed of the 
pace 



ave 



An integer specifying the average delay for the speed of 
the pace 



max 



An integer specifying maximum delay for the speed of the 
pace 



Comments 

Pacing functions can be inserted into your script file to control the pace 
of the script. These functions cause the script to pause long enough to 
make the script send transactions to the SUT at a predetermined 
throughput Typically used in a loop, these functions may be nested to 
permit controlled throughput of transactions within a larger transaction. 

Pacetne () has an average throughput that will be maintained, but 
submission of transactions occur at frequencies other than that defined 
by a constant distribution. 

Pacetne ( ) accepts three arguments to identify the speed of the pace - 
a minimum, average, and maximum delay. The average will be 
maintained during sustained execution of the script. Each time 
Pacetne ( ) is executed, it will delay for a number of seconds since the 
last execution, where the number is taken from a truncated, negative 
exponential distribution defined by the three values. In a typical such 
distribution, the average is relatively close to the minimum. For 
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example, if Pacetne(" query" , 7.0, 10.0, 20.0) is used in a script, 
a sequence of 7, 8, 10, and 15 second delays is possible. The average of 
the delays is still ten seconds. Pacetne { ) will select the values for delay 
accurate to l/10th of a second, so 9.2 seconds is a possible value. 

Note: You are permitted to nest pacing functions in a script If you do 
so, we recommend setting the starting point for a pace explicitly, i.e. 
with the speed argument of 0. This will ensure that an inner loop 
executed at a fixed pace will begin execution immediately every time 
that the loop begins. 

RETURN VALUE This function returns the amount of time delayed 

SEE ALSO Paceconstant, Paceuniform 
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FUNCTION 



Paceuniform 



SYNTAX 



Paceuniform (str, min, max) 



char *str; 



int min, max; 



DESCRIPTION 



Parameters 



str 



An argument naming the pace 



min 



The minimum delay for the speed of the pace 



max 



The maximum delay for the speed of the pace 



Comments 

Paceunif orm( ) has an average throughput that will be maintained, but 
submission of transactions occurs at frequencies other than that defined 
by a constant distribution. 

Paceunif orm( ) accepts two arguments to identify the speed of the 
pace - a minimum delay and a maximum delay. The average of the two 
will be maintained during sustained execution of the script. Each time 
Paceunif orm( ) is executed, it will delay for a number of seconds since 
the last execution, where the number is taken from a uniform 
distribution between the minimum and maximum values. For example, 
if Paceunif orm( "query " , 8.0, 12.0) is used in a script, a sequence 
of 9, 11, 8, 10, and 12 second delays is possible (assuming the query has 
a response time of zero seconds.) The average of the delays is still ten 
seconds. Paceuniformt ) will select the values for delay accurate to 
l/100th of a second, so 9.27 seconds is a possible value. 



RETURN VALUE This function returns the amount of time delayed. 



SEE ALSO 



Paceconstant, Pacetne 
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FUMCTIOM 



Parse 



SYNTAX 



Parse { curnum, sqlstmt, .../* args */) 



int curnum; 



char * sqlstmt, *args; 



DESCRIPTION Parameters 

curnum An identifier of the cursor structure opened with the 
associated Open ( ) 



Comments 

This function is inserted into the script when a SQL statement is parsed 
and sent to the SUT. The Parse { ) function parses a SQL statement and 
associates it with a cursor identified in the parameter curnum. The 
parameter sqlstmt is a string that lists the SQL statement 

During script execution, Parse ( ) sends the SQL statement to the SUT 
and verifies that the syntax of the SQL statement is compatible with the 
SUT. The SQL statement is stored on the SUT to be executed with a 
subsequent Exec { ) call. This operation prepares the SUT for 
processing of the SQL statement by such functions as Define () or 
Bind { ) , Describe ( ) , Data ( ) , etc. 

Note: You may edit this function to accept variable arguments in a way 
similar to the C function print f ( ) . The Parse ( ) function will accept 
arguments so that data can be passed into the script from the command 
line. Arguments are passed to this function via the script execution 
statement. In the script execution command, arguments follow the 
names of the executable script file and the log file, and all arguments 
must be string pointers. The string conversion specification is provided 
by the characters %s. 



sqlstmt The SQL statement to be parsed 



args 



Optional variable arguments 
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RETURN VALUE If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 



EXAMPLES The following example demonstrates selecting the data for a query in 

a SQL statement for the cursor structure curi: 



Parse (CUR1, " SELECT EMPNO, ENAME, JOB, MGR, HIREDATE, 
SAL, C0MM, DEPTNO FROM EMP, UPDATE OF EMPNO, ENAME, 
JOB, MGR, HIREDATE , SAL, COMM, DEPTNO"); 



SEE ALSO Exec, Fetch 
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FUNCTION 



Password 



SYNTAX 



Password ( lognum, password) 
int lognum; 
char *password; 



DESCRIPTION Parameters 

lognum An identifier of a logon communication structure 

password The user password used to access the database 



Comments 

To successfully access or logon to the database, a Username and 
Password must be entered The Password () function is inserted into 
the script file when a user password is entered to logon to the database. 
During script execution, this function is used in the process of 
accessing the SUT. This function will occur in the script before a 
Logon {) function. 



Note: Because this function is inserted into your script based on how 
the client application interacts with the SUT, you should not attempt to 
edit this function or remove it from the script. If you change this 
function from when it was captured you may drastically alter the 
expected behavior of the client and SUT and therefore, break the script 
during execution, 

RETURN VALUE If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 



EXAMPLES In the following example, the script will attempt to logon to the 

database oracle on the logon structure logi with the password 
tiger: 
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Username ( L0G1 , " scott@FOO " ) ; 
Password (LOG1, "tiger") ; 
Logon ( ORACLE , LOG1 ) ; 



SEE ALSO AppName, Hostname, Language, Servername, Username 
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FUNCTION 



Pause 



SYNTAX 



Pause ( lognum, str) 
int lognum, str; 



DESCRIPTION Parameters 

lognum An identifier of a logon communication structure 



str The id of the transaction to be paused 

Comments 

The Pause () function specifies an application-defined database 
transaction in progress that is to be suspended until a Continue ( ) call 
is executed. This function is captured into the script when the client 
application instructs the database to halt execution of the current 
transaction. It will be inserted following the associated Transaction ( ) 
function. 

The transaction id, str parameter, assigned in the Pause ( ) function is 
lated used in the Continue!) function to continue work on the 
transaction. 

RETURN VALUE If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 

EXAMPLES The following example demonstrates the PauseO function within a 
script 



BeginTransaction (LOGl) ; 

Pause ( LOGl , TRANS2 ) ; 

Continue ( LOGl , TRANS 1) ; 
Commit (TRANS 1) ; 
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SEE ALSO BeginTransaction, Continue 
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FUNCTION Pointerrate 

SYNTAX double Pointerrate (n) 

double n; 

DESCRIPTION Parameters 

n The mouse pointer speed measured in points per second 

Comments 

Pointerrate ( ) sets the emulated mouse pointer speed for a script. 
Pointer speed is measured in points per second which is specified in 
the parameter n. The default pointer rate Pointerrate (100) which is 
listed at the top of each script created by EMPOWER/CS. You may 
change this default when editing the script file. Multiple Pointerrate ( ) 
functions may be used in a script to specify, for example, different 
pointer rates when using different applications. 

During script execution, each time that the emulated user is supposed 
to be moving the PC mouse, the script will pause a length of time 
defined as the number of points to be moved times the specified 
pointer rate. For example, if the emulated user must move the mouse 
100 points and the pointer rate is specified as 50 points per second 
(pointerrate (50)) then the script will pause two seconds during each 
mouse point from one location to the next specified location. 

Care must be taken when inserting Pointerrate ( ) functions into a 
script The response time statistics for scenarios and functions are 
generated from the user's perspective. Therefore, they will take into 
account the time it takes for the emulated user to move the PC mouse. 
This is particularly important when you are comparing the performance 
of similar scripts. Any Pointerrate { ) functions inserted into one 
script must be inserted in the same locations in the other script(s) to 
provide a meaningful comparison. 
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error if you set rate at less than zero, script will abort and you will 
receive an error message. 

RETURN VALUE This function returns the old pointer rate value. 



EXAMPLES In the following example, the Pointerrate ( ) is set at the beginning 

of the script at 150 points per second: 





/* EMPOWER/ CS VI. 0.1 Remote Terminal Emulator Script */ 




Typerate ( 5 ) ; 


/* Typing delay in CPS */ 




Pointerrate (150) ; 


/* Pointerrate in PPS */ 




Thinkuniform{l, 2.5) ; 


/* Think delay */ 




Seed(getpid{) ) ; 


/* Seed random number generator */ 




Timeout(300, CONTINUE); 


/* What to do if function takes too long */ 




Dberror (CONTINUE) ; 


/* What to do on Database errors */ 




Unset (NOTIFY) ; 


/* Don't display warnings. I'll use Mon to find them */ 



SEE ALSO Typerate 
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FUNCTION Range 

SYNTAX int Range (min, max) 

int min, max; 



DESCRIPTION Parameters 

min An integer specifying the minimum value of the range 



max 



An integer specifying the maximum value of the range 



Comments 

Range () often is used with the sleep {) function to perform random 
execution delays. This function is inserted into the script file during 
script editing. 

Range ( ) returns a random number. 

RETURN VALUE Range ( ) returns a random integer number between or equal to min 
and max. 

EXAMPLES The following script segment is an example of how to perform a 

random execution delay from 0 to 60 seconds. 

Sleep (Range (0, 60) ) ; 



SEE ALSO 



Seed, Sleep 
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FUNCTION 



RightButtonDown 



SYNTAX 



void RightButtonDown (x,y) 
unsigned int x,y; 



DESCRIPTION Parameters 

x The on screen x coordinate of the PC mouse 



y The on screen y coordinate of the PC mouse 
Comments 

The RightButtonDown ( ) function is inserted in the script file 
automatically during Capture when the user depresses the right mouse 
button down. During script execution in Display mode, this function is 
used to emulate pressing the right mouse button down. In Non-Display 
mode, this function is used to emulate the pointer rate delay based on 
the x,y parameters. 

The x,y parameters indicate the position of the mouse on screen at the 
time the button was pressed. 

The RightButtonDown ( ) function may be edited in your script file, but 
because you change the activity as it was captured, you run the risk of 
breaking the script If you change this function, you must be sure to 
change the associated Right ButtonUp ( ) function. 



RETURN VALUE (not applicable) 



EXAMPLES 



The following example demonstrates various mouse button activities: 
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AppWait (5 .21) ; 
WindowRcv { " Pt " ) ; 

Lef tButtonDown(213 , 111) ; 



AppWait (0.55) ; 
WindowRcv { "Pt" ) ; 

LeftButtonUp(222,195) ; 



AppWait (0.38) ; 
WindowRcv ("Pt") ; 

RightButtonDown(340, 216) ; 
RightButtonUp{333,219) ; 

AppWait (0.17) ; 
WindowRcv ( "Pt" ) ; 

Ri ght Bu 1 1 onPr es s ( 3 2 5 , 2 2 6 ) ; 



Sometimes a comment is added before a button event to add context to 
the script. In this example, the comment indicates double clicking a 
button called Tetch." 



/* Clicked (Button) (FETCH) */ 
RightDblPress(276,345) ; 



SEE ALSO RightButtonPress, RightButtonUp, RightDblPress 
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FUNCTION 



RightButtonPress 



SYNTAX 



void RightButtonPress {x, y) 
unsigned int x,y; 



DESCRIPTION Parameters 

x The on screen x coordinate of the PC mouse 

y The on screen y coordinate of the PC mouse 
Comments 

The RightButtonPress ( ) function is inserted in the script file 
automatically during Capture when the right button on the PC mouse 
was pressed down and released. A RightButtonPress () is inserted in 
the script when two consecutive RightButtonDown/Up events do not 
have any other user events between them. 

The x,y parameters indicate the position of the mouse on screen at the 
time the button was pressed 

During script execution in Display mode, this function is used to 
emulate pressing the left mouse button down. In Non-Display mode, this 
function is used to emulate the pointer rate delay based on the x , y 
parameters. 

The RightButtonPress { ) function may be edited in your script file, 
but because you change the activity as it was captured, you run the risk 
of breaking the script 

RETURN VALUE (not applicable) 



EXAMPLES 



The following example demonstrates various mouse button activities: 
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AppWait (5.21) ; 
WindowRcvC'Pt") ; 

LeftButtonDown(213, 111) ; 



AppWait (0.55) ; 
WindowRcv ( " Pt " ) ; 

LeftButtonUp<222, 195) ; 



AppWait (0.38) ; 
WindowRcvC'Pt") ; 

RightBut tonDown (340,216); 
RightButtonUp(333,219) ; 



AppWait (0.17) ; 
WindowRcv ("Pt") ; 



RightButtonPress (325, 226) ; 



Sometimes a comment is added before a button event to add context to 
the script In this example, the comment indicates double clicking a 
button called "Fetch." 



/* Clicked (Button) (FETCH) 
RightDblPress<276,345) ; 



SEE ALSO RightButtonDown, RightButtonUp, RightDblPress 
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FUNCTION RightButtonUp 

SYNTAX void RightButtonUp (x,y) 

unsigned int x,y; 

DESCRIPTION Parameters 

x The on screen x coordinate of the PC mouse 

y The on screen y coordinate of the PC mouse 
Comments 

The RightButtonUp!) function is inserted in the script file 
automatically during Capture when the user releases the right mouse 
button. During script execution in Display mode, this function is used to 
emulate pressing the right mouse button down. In Non-Display mode, 
this function is used to emulate the pointer rate delay based on the x, y 
parameters. 

The x,y parameters indicate the position of the mouse on screen at the 
time the button was released 

The RightButtonUp () function may be edited in your script file, but 
because you change the activity as it was captured, you run the risk of 
breaking the script If you change this function, you also must change 
the associated RightButtonDown ( ) function. 

RETURN VALUE (not applicable) 

EXAMPLES The following example demonstrates various mouse button activities: 
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AppWait (5. 21) ; 
WindowRcv ( " Pt 11 ) ; 

LeftButtonDown{213, 111) ; 



AppWait (0.55) ; 
WindowRcv ( 11 Pt" ) ; 

LeftButtonUp(222, 195) ; 



AppWait (0.38) ; 
WindowRcv ( " Pt 11 ) ; 

RightButtonDown{340, 216) ; 
RightButtonUp(333 / 219) ; 

AppWait (0.17) ; 
WindowRcv ("Pt") ; 

RightButtonPress (325, 226) ; 



Sometimes a comment is added before a button event to add context to 
the script. In this example, the comment indicates double clicking a 
button called 'Fetch." 



/* Clicked (Button) (FETCH) */ 
RightDblPress{27 6, 345) ; 



SEE ALSO RightButtonDown, RightButtonPress, RightDblPress 
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FUNCTION 



RightDblPress 



SYNTAX 



void RightDblPress (x,y) 
unsigned int x,y; 



DESCRIPTION Parameters 

x The on screen x coordinate of the PC mouse 



y The on screen y coordinate of the PC mouse 
Comments 

The RightDblPress { ) function is inserted in the script file 
automatically during Capture to indicate that a double press of the right 
mouse button occurred. During script execution in Display mode, this 
function is used to emulate a double click of the right mouse button. In 
Non-Display mode, this function is used to emulate the pointer rate 
delay based on the x,y parameters. 



The x,y parameters indicate the position of the mouse on screen at the 
time the button was double-clicked during Capture. 

The RightDblPress () function may be edited in your script file, but 
because you change the activity as it was captured, you run the risk of 
breaking the script 



RETURN VALUE (not applicable) 



EXAMPLES 



The following example demonstrates various mouse button activities: 
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AppWait (5 .21} ; 
WindowRcv( "Pt" ) ; 

LeftButtonDown(213,lll) ; 



AppWait (0.55) ; 
WindowRcvpPt" ) ; 

LeftButtonUp(222, 195) ; 



AppWait (0.38) ; 
WindowRcv{ "Pt" ) ; 

RightButtonDown(340,216) ; 
RightButtonUp{333 / 219) ; 

AppWait (0.17) ; 
WindowRcvC'Pt" ) ; 

RightButtonPress (325, 226) ; 



Sometimes a comment is added before a button event to add context to 
the script. In this example, the comment indicates double clicking a 
button called Tetch." 



/* Clicked (Button) (FETCH) */ 
RightDblPress (276, 345) ; 



SEE ALSO RightButtonDown, RightButtonPress, RightButtonUp 
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FUNCTION 
SYNTAX 



Rollback 

Rollback (num) 
int num; 



DESCRIPTION Parameters 

num A logon or cursor communication structure 



Comments 

The Rollback {) function is inserted into the script when database 
transactions are rolled back from the database since data was last 
committed or an Open ( ) occurred. Rollback ( ) restores the database to 
its original state since the last Commit ( ) was executed. 

RETURN VALUE If the function is successful, zero is returned If an error occurs, -1 is 
returned. 



EXAMPLES 



SEE ALSO 



This example demonstrates a Rollback { ) function in a script file: 



Commit (CURl) ; 




/* insert data into database */ 
Parse (CURl, "insert empno, ename, 


empjob into emp_table" ) ; 


Bind ( CURl , " empno " , INT , 4 ) ; 
Bind (CURl , "ename", STRING, 30); 
Bind { CURl , " emp j ob " , STRING , 20); 




/* 123 refers to empno, Smith — 
Data (CURl, "123 | Smith | typist" ) ; 


ename, typist empjob */ 


Exec (CURl) ; 




Rollback (CURl) ; 




Commit 


■ EMPOWER/CS-Vl.O.l ^^^^^^^^^H 
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FUNCTION 



Seed 



SYNTAX 



int Seed(n) 
int n; 



DESCRIPTION Parameters 

n The value used to seed the random number generator 

Comments 

SeedO seeds the random number generator used by EMPOWER/CS 
that produces random think time values. 

If you wish to generate the same sequence of think times during 
repeated script executions, you should always seed the random number 
generator in the script with the same value. If you wish to generate 
different sequences of think times for each script in a multi-user 
emulation, you should seed each random number generator in each 
script with a different value. 

RETURN VALUE Seed returns a value of n. 

EXAMPLES The following example Seed{ ) function seeds the random number 

generator from an argument specified on the command line used to 
execute the script 

Seed(atoi (argv[3] ) ) ; 



SEE ALSO 



Thinkconstant, Thinktne, Thinkuniform, Range 
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FUNCTION 



Servername 



SYNTAX 



Servername ( lognum, servername ) 

int lognum; 

char *servername; 



DESCRIPTION 



Parameters 



lognum 



An identifier of a logon communication structure 



servername The name of the database server 
Comments 

This function is inserted into the script when a server name was 
specified for a logon connection. It will occur in the script before a 
Logon () call. 

Servername ( ) sets the name of the database server to which the user 
connected 

Note: Because this function is inserted into your script based on how 
the client application interacts with the SUT, you should not attempt to 
edit this function or remove it from the script If you change this 
function from when it was captured in the script file, you may drastically 
alter the expected behavior of the application and SUT and therefore, 
break your script during execution. 



RETURN VALUE If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 
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EXAMPLES The following example demonstrates the Servername ( ) function in a 

script: 



Servername ( LOG1 , " DBSERVER" ) ; 
Username ( LOG1 , "joe") ; 
Password (L0G1 , "xapq" ) ; 
Logon ( SYBASE , L0G1 ) ; 



SEE ALSO AppName, Hostname, Language, Password, Username, 
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FUNCTION 



Set 



SYNTAX 



long Set(n) 
long n; 



DESCRIPTION Parameters 

n The EMPOWER/CS option turned on 

Comments 

Set ( ) turns on EMPOWER/CS options during script execution. Valid 
options are listed below: 



OPTION 

LCMD 
FLUSH 

NOBUF 
NOTIFY 

BELL 
LOGGING 



DESCRIPTION 

log miscellaneous commands 

flush SUT responses to the log that are detected after a 

pattern match in a windowRcv ( ) 

don't use buffered writes to the log file 

display a message when a timeout occurs, execution is 

suspended, or execution resumes 

ring the bell twice when a timeout occurs 

enable logging 



Default options are lcmd and logging. 



RETURN VALUE Set ( ) returns a long value that contains previously set options. 



EXAMPLES The following script segment causes flushing of the remaining buffer 

after the pattern is found and immediate recording of every response 
character in the log file. 



Set (FLUSH) ; / * turn flush buffer on*/ 

Set (NOBUF) ; /* turn immediate recording on 



SEE ALSO Unset 
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FUNCTION 



SetlntVar 



SYNTAX 



SetlntVar (curnum, var, value) 
int curnum; 
char * var; 
int value; 



DESCRIPTION Parameters 

cumuin A cursor communication structure 

var The name of the variable 

value The new value to be assigned to the variable 

Comments 

The SetlntVar {) function assigns a new value to the specified integer 
variable in the parameter var. The new value is assigned in the 
parameter value. This function is inserted into your script file when 
editing and should occur before ExecO or after GetVarO or 
GetNextRow{ ). 

RETURN VALUE After the new value has been assigned to the specified variable, the 
original value of the variable is returned. 



SEE ALSO 



GetlntVar, GetVar, SetVar 
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FUNCT10M SetVar 



SYNTAX SetVar (curnum, var, value) 

int curnum; 
char *var f *value; 



DESCRIPTION Parameters 

curnum A cursor communication structure 

var The name of the variable 

value The new value to be assigned to the variable 

Comments 

The SetVar ( ) function assigns a new value to the specified variable in 
the parameter var. The new value is assigned in the parameter value. 
You can insert this function into your script file when editing. 

RETURN VALUE After the new value has been assigned to the specified variable, the 
original value of the variable is returned. 

EXAMPLES The following example demonstrates using this function in a script 



char * empname , * empno ; 



Parse (CUR1, "insert ename, empno, empjob into 
employee_table" ) ; 

Bind(CURl, "ename", STRING, 50); 
Bind(CURl, "empno", INT, 4) ; 
Bind(CURl, "empjob", STRING, 30); 

(continued on following page . . .) 
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Data(CURl, " Smith | 234 | typist " ) ; 




/* inserts " Smith | 234 | typist " into database 
Exec (CUR1) ; 


*/ 


empno=Ge tVar ( CUR1 , " empno " ) ; 




for (i=0 ; i<5; i++) { 
/* this increments the value of empno by 1 
* empno =* ( int * ) empno +i ; 
Se tVar ( CUR1 , " empno " , empno ) ; 


every time */ 


/* this reads in a unique name from a name 
empname=Fioreadf ield{ "namef ile n ) ; 
SetVar (CUR1 , " empname " , empname ) ; 


file everytime */ 


/* inserts "new name | empno+1 | typist " into 
Exec (CUR) ; 

} 


database */ 



SEE ALSO GetlntVar, QetVar, SetlntVar 
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FUNCTION Sleep 

SYNTAX double Sleep (n) 

double n; 

DESCRIPTION Parameters 

n The number of seconds to suspend script execution 

Comments 

sleep () suspends script execution for n seconds simulating a think 
delay. 

RETURN VALUE sleep ( ) returns n. 

EXAMPLES In the following example, Sleep ( ) specifies that script execution will 

suspend for 30 seconds: 

Sleep (30) ; 

You can also specify a range for the Sleep { ) parameter 
Sleep (Range (40, 60) ) ; 
SEE ALSO Think, Thinkconstant, Thinktne, Thinkuniform 
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FUNCTION Sql 

SYNTAX Sql (curnum, sqlstmt, . ../* args */) 

int curnum; 
char * sqlstmt, *args; 

DESCRIPTION Parameters 

curnum An identifier of the cursor structure opened with the 
associated Open { ) 

sqlstmt The SQL statement to be parsed 

args Optional variable arguments 

Comments 

This function is inserted into the script when a SQL statement is parsed 
and sent to the SUT. The Sql ( ) function parses a SQL statement and 
associates it with a cursor identified in the parameter curnum. The 
parameter sqlstmt is a string that lists the SQL statement 

During script execution, Sql { ) sends the SQL statement to the SUT 
and verifies that the syntax of the SQL statement is compatible with the 
SUT, The SQL statement is stored on the SUT to be executed with a 
subsequent ExecO call. This operation prepares the SUT for 
subsequent processing of the SQL statement with such functions as 
Define ( ) or Bind ( ) , Describe ( ) , Data ( ) , etc 

The Sql ( ) statement is called before an Exec ( ) in the script. 

Note: You may edit this function to accept variable arguments in a way 
similar to the C function print f ( ) . The sql ( ) function will accept 
arguments so that data can be passed into the script from the command 
line. Arguments are passed to this function via the script execution 
statement. In the script execution command, arguments follow the 
names of the executable script file and the log file, and all arguments 
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must be string pointers. The string conversion specification is provided 
by the characters %s. 

RETURN VALUE If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 

EXAMPLES The following example demonstrates selecting the data for a query in 

a SQL statement for the cursor structure curI: 



SqKCURl, " SELECT EMPNO, ENAME, JOB, MGR, HIREDATE, 
SAL, COMM, DEPTNO FROM EMP, UPDATE OF EMPNO, ENAME, 
JOB, MGR, HIREDATE, SAL, COMM, DEPTNO"); 



SEE ALSO Exec, Fetch, Parse 
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FUNCTION SqlExec 



SYNTAX SqlExec (lognum, sqlstmt, . ../* args */} 

int lognum; 
char * sqlstmt, *args; 



DESCRIPTION Parameters 

lognum Specifies a logon communication structure 

sqlstmt Lists the SQL statement to be executed 

args Optional variable arguments 



Comments 

A SqlExec () function is inserted into your script when a SQL 
statement was executed that contained no input or output variables. The 
SqlExec () function executes the SQL statement on the SUT 
completing four database operations. It opens a cursor, parses a SQL 
statement, executes the Parse { ) , and closes the cursor. 



When this function is used, no operations such as Describe ( ) , Bind ( ) , 
Defined, Fetch { ), etc., are completed. For example, it may be used 
when a SQL statement requires only the joining of two tables. 

Note: You may edit this function to accept variable arguments in a way 
similar to the C function printf ( ) . The SqlExec ( ) function will accept 
arguments so that data can be passed into the script from the command 
line. Arguments are passed to this function via the script execution 
statement. In the script execution command, arguments follow the 
names of the executable script file and the log file, and all arguments 
must be string pointers. The string conversion 'specification is provided 
by the characters %s. 

RETURN VALUE If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 
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SEE ALSO Exec, Parse, Sq] 
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FUNCTION Suspend 
SYNTAX Suspend ( ) ; 

DESCRIPTION Suspend ( ) is used during script execution to suspend a script until 

the signal sigresume arrives. Suspending script execution is useful 
when multiple scripts are executed simultaneously. Use of the suspend 
feature permits control and synchronization of concurrent scripts. 

If the lcmd (a default option) option is set with Set ( ) , a suspended 
message with the time stamp of the suspension will be recorded in the 
log file, A sample of the suspend message in the log file is shown 
below: 

»> 33 Suspend () 13 :37:06.96 

Once a script has been suspended, execution can be resumed in three 
ways. First, if the script was started with the Mix tool, the execution of 
the script can be resumed with the Mix resume command. Second, if 
the script is started at the UNIX script driver shell prompt, the UNIX 
kill command can be used to send the sigresume signal to the script 
process. See $EMPOWER/h/ empower .h for the sigresume value on 
your system. You also can resume scripts from Monitor with the "r" 
commands 

If the lcmd (a default option) option is set, a resume message with a 
time stamp will be recorded in the log file. A sample of the resume 
message is shown below: 

»> 33 Resume () 13:37:30.54 

RETURN VALUE If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 

SEE ALSO kill { 1 ) in your UNIX User's Guide 
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FUNCTION SysKeyDown 

SYNTAX void SysKeyDown (key) 

unsigned int key; 

DESCRIPTION Parameters 

key A Microsoft Windows virtual key code value 



The SysKeyDown () function is inserted in the script file automatically 
during Capture to indicate that a keyboard key on the PC was 
depressed while the Alt key was held down. 'Sys* implies that the 
keystrokes are being sent to the System Menu of the current window. 
During script execution in Display mode, this function is used to 
emulate pressing the specified key down with the Alt key. In Non- 
Display mode, this function emulates type delay for pressing the key. 

The parameter key represents a Microsoft Windows virtual key code 
value. Some examples of valid virtual key codes are vk_space, 

VK_DELETE, VK_BACK, VKJDOWN, and VK_UP. 

Key events may be edited in your script file, but because you change 
the activity as it was captured, you run the risk of breaking the script 

RETURN VALUE (not applicable) 



EXAMPLES The following example script segment demontrates using various key 

events. In this case, the user pressed the Alt key (vk_menu) and then 
pressed and released the F key. Then the user released the Alt key and 
pressed the left arrow key, and pressed and released the c key: 
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CurrentWindow (" Program Manager - [Empower/CS] " , 3 6 , 24 , 324 , 543 ) ; 
Think (2. 14) ; 

Sys KeyDown ( VK_MENU ) ; 
SysKeyPress{ ' F' ) ; 
SysKeyUp(VK_MENU) ; 
KeyPress (VK_LEFT) ; 

TypeC'c" ) ; 



SEE ALSO 



KeyDown, KeyPress, KeyUp, SysKeyPress, SysKeyUp 
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FUNCTION SysKeyPress 

SYNTAX void SysKeyPress (key) 

unsigned int key; 

DESCRIPTION Parameters 

key A Microsoft Windows virtual key code value 

Comments 

A SysKeyPress ( ) is inserted in the script file during Capture and 
translates into a down/up key sequence while the Alt key is held down. 
A SysKeyPress { ) indicates that no user events have occurred 
between a SysKeyDown/Up. If the key is the same for consecutive 
SysKeyDown and SysKeyUp events, the key events automatically will 
be translated into a SysKeyPress. 'Sys' implies that the keystrokes are 
being sent to the System Menu of the current window. 

During script execution in Display mode, this function is used to 
emulate pressing and releasing the specified key. In Non-Display mode, 
this function emulates the type delay for pressing and releasing the key. 

The parameter key represents a Microsoft Windows virtual key code 
value. Some valid virtual key codes are vk_space, vk_delete, 
vk_back, vkjdown, and VKJJP. 

Key events may be edited in your script file, but because you change 
the activity as it was captured, you run the risk of breaking the script 

RETURN VALUE (not applicable) 

EXAMPLES The following example script segment demontrates using various key 

events. In this case, the user pressed the Alt key (vk_menu) and then 
pressed and released the F key. Then the user released the Alt key and 
pressed the left arrow key, and pressed and releasing the c key: 
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t 

CurrentWindow( "Program Manager - [Empower/CS ] " , 3 6 , 24 , 324 , 543 ) ; 



Think (2 .14) ; 



SysKeyDown (VK_MENU) ; 
SysKeyPress ( ' F' ) ; 
SysKeyUp(VK_MENU) ; 
KeyPress (VK_LEFT) ; 



Typepc") ; 



SEE ALSO KeyDown, Keyllp, SysKeyDown, SysKeyPress, SysKeyUp 
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FUNCTION 



SysKeyUp 



SYNTAX 



void SysKeyUp (key) 
unsigned int key; 



DESCRIPTION Parameters 

key A Microsoft Windows virtual key code value 

Comments 

The SysKeyUp () function is inserted in the script file automatically 
during Capture and indicates that a keyboard key on the PC was 
released while the Alt key was held down. 'Sys 1 implies that the 
keystrokes are being sent to the System Menu of the current window. 
During script execution in Display mode, this function is used to 
emulate a releasing the specified key. In Non-Display mode, this 
function emulates the type delay for the key event 

The parameter key represents a Microsoft Windows virtual key code 
value. Some valid virtual key codes are vk_space, vk_delete, 
vk_back, vk_down, and VK_UP. 

Key events may be edited within the script file, but because you change 
the activity as it was captured, you run the risk of breaking the script 



RETURN VALUE (not applicable) 

EXAMPLES The following example script segment demontrates using various key 

events. In this case, the user pressed the Alt key (vk_menu) and then 
pressed and released the F key. Then the user released the Alt key and 
pressed the left arrow key, and pressed and released the c key: 
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CurrentWindow { 11 Program Manager - [Empower/CS] " , 36 , 24 , 324 , 543 ) ; 
Think{2.14) ; 

Sys Key Down (VK_MENU) ; 
SysKeyPress { ' F ' ) ; 
SysKeyUp(VK_MENU) ; 
KeyPress (VK_LEFT) ; 

Type ( " c " ) ; 



KeyUp, KeyPress, KeyDown, SysKeyDown, SysKeyPress 
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FUNCTION Think 

SYNTAX double Think (n); 

double n; 



DESCRIPTION Parameters 

n The amount of think delay measured in seconds 

Comments 

During script execution, Think ( ) performs a delay to emulate a user's 
think time. The delay will be determined by the current think time 
distribution. 

The think time distribution can be defined by any of the four think time 
distribution functions: 

Thinkactual ( ) - actual think time 

Thinkconstant { ) - constant distribution 

Thinktne { ) - truncated negative exponential distribution 

Thinkuniform( ) * uniform distribution 

Think ( ) functions are inserted in the script file during Capture when 
the EMPOWER/CS user pauses before performing any activity. During 
Capture, you may specify the number of seconds that EMPOWER/CS 
will wait before inserting a Think { ) function into the script file. The 
Think ( ) function is inserted in the captured script file only after the 
specified time has elapsed. The parameter of the Think {) function 
specifies the amount of seconds elapsed 

Because the script was captured with a think time value, you must 
always have a value specified in the Think { ) functions during script 
execution (even if the value is zero) regardless of the think time 
distribution. 
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The functions for think time distribution can be placed anywhere in the 
script to emulate thinking delay of a real user based upon your testing 
needs. 

RETURN VALUE Think { ) returns the amount of delay time incurred. 



EXAMPLES The following example script segment demonstrates that the user 

paused before pressing two of the buttons during the Capture 
session: 





Think (5. 11 ) ; 








ButtonPush ( " Employee 


Records 


Next" , 726, 439) ; 


■ ?■ ~ 


AppWait (2 .09) ; 
WindowRcvpSfPt" ) ; 








ButtonPush { " Employee 


Records 


Next" ,726,439) ; 




ButtonPush ( " Employee 


Records 


Delete" ,714,344) ; 




WindowRcvC'SfPt" ) ; 








Think(3,70) ; 








ButtonPush ( " Employee 


Records 


Close'\714,157) ; 



The following script segment defines the constant think time 
distribution to be three seconds and will perform a think delay only 
when Think ( ) functions are executed. 



Thinkconstant (3 ) ; 
Think{1.23) ; 



SEE ALSO Seed, Thinkactual, Thinkconstant, Thinktne, Thinkuniform 
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FUNCTION 



Thinkactual 



SYNTAX 



Thinkactual ( ) ; 



DESCRIPTION During Capture, you may specify the number of seconds that 

EMPOWER/CS will wait before inserting a Think ( ) function into the 
script file. The Think ( ) function is inserted in the captured script file 
only after the specified time has elapsed. By default, if no activity is 
captured after two seconds, EMPOWER/CS will insert a think time 
function of at least two seconds and the time elapsed until the next 
action occurs. The parameter of the Think ( ) function specifies the 
amount of seconds elapsed. 

During script execution, Thinkactual ( } tells the script to use the actual 
Think ( ) functions and values that were captured during your Capture 
session. 

RETURN VALUE (not applicable) 



EXAMPLES The following example demonstrates using this function within a 

script. When you edit your script, insert Thinkactual ( ) as shown 
below: 
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/* EMPOWER/ CS VI. 0 


1 Remote Terminal Emulator Script */ 


Typerate(5) ; 


/* Typing delay in CPS */ 


Pointerrate(150) ; 


/* Pointerrate in PPS */ 


Thinkactual ( ) ; 


/* Think delay */ 


Seed(getpid() ) ; 


/* Seed random number generator */ 


Timeout (300, CONTINUE);/* What to do if function takes too long */ 


Dberror { CONTINUE ) ; 


/* What to do on Database errors */ 


Unset (NOTIFY) ; 


/* Don't display warnings. I'll use Mon to find them */ 


Beginscenario ( "exanplel" ) ; 



O SEE ALSO Think, Thinkconstant, Thinktne, Thinkuniform 
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FUNCTION Thinkconstant 

SYNTAX void Thinkconstant ( f ) 

double f; 

DESCRIPTION Parameters 

f The amount of thinking delay measured in seconds 

Comments 

Thinkconstant { ) defines a constant think time distribution. The 
argument f is a double value that specifies the amount of thinking delay 
in seconds. 

Think delay will be performed whenever a Think () function is 
executed 

The think time distribution will be active until it is reset by another think 
time distribution function. 

Multiple Thinkconstant { ) functions can be inserted throughout the 
script file when editing your script. 

RETURN VALUE (not applicable) 

EXAMPLES The following script segment demonstrates how to generate think 

times from a constant distribution of three seconds and perform think 
delay only when Think ( ) functions are executed: 



Thinkconstant ( 3 ) ; 
Think (0) ; 



SEE ALSO Think, Thinkactual, Thinktne, Thinkuniform 
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FUNCTION 



Thinktne 



SYNTAX 



void Thinktne (min, avg, max) 
double min, avg, max; 



DESCRIPTION Parameters 

min The minimum value of the think time distribution 

avg The average value of the think time distribution 

max The maximum value of the think time distribution 



Comments 

Thinktne {) defines a truncated negative exponential think time 
distribution. The parameters min, avg, and max are double values that 
specify the minimum, average, and maximum values of the distribution, 
respectively. The values are in seconds. 

Think delay will be performed whenever a Think {) function is 
executed 

The think time distribution will be active until it is reset by another think 
time distribution function. The SeedO function (which seeds the 
EMPOWER/CS random number generator) helps to determine think 
delays for this think time distribution. 

Multiple Thinktne { ) functions can be inserted throughout the script 
file when editing your script 



RETURN VALUE (not applicable) 

EXAMPLES The following script segment is an example of how to generate think 

times from a truncated negative exponential distribution. The minimum 
value is 2 seconds, the average value is 5 seconds, and the maximum 
value is 25 seconds: 



EMPOWER/CS-Vl.0.1 



2-272 

Copyright PERFORMIX, Inc. 0 1995 



User's Guide— Reference 



Thinktne(2.0, 5.0, 25.0); 
Think { ) ; 



SEE ALSO Seed, Think, Thinkactual, Thinkconstant, Thinkuniform 



O 

m 

m 

O 

m 
m 
0 
o 
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FUNCTION 



Thinkuniform 



SYNTAX 



void Thinkuniform (min, max) 
double min, max; 



DESCRIPTION Parameters 

min The minimum value of the think time distribution 

max The maximum value of the think time distribution 

Comments 

Thinkunif orm( } defines a uniform think time distribution. The 
parameters min and max are double values that specify the range of 
think delay in unit of seconds. 

Think delay will be performed whenever a Think () function is 
executed. 

The think time distribution will be active until it is reset by another think 
time distribution function. The seed() function (which seeds the 
EMPOWER/CS random number generator) helps to determine think 
delays for this think time distribution. 

Multiple Thinkunif orm{ ) functions can be inserted throughout the 
script file when editing your script. 



RETURN VALUE (not applicable) 
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The following script segment is an example of how to generate think 
times from a uniform distribution between 30 and 45 seconds and 
perform think delay only when Think () functions are executed. 



Thinkuniform{30, 45) ; 
Think { ) ; 



Seed, Think, Thinkactual, Thinktne, Thinkuniform 



EMPOWER/CS-Vl.0.1 



2-275 

Copynght PERFORMIX. Inc. © 1 995 



User's Guide-Reference 



FUNCTION Time 

SYNTAX void Time(p) 

struct timevalue *p; 

DESCRIPTION Parameters 

p A structure where the current time on the UNIX driver will be stored 

Comments 

Time { ) obtains the current time on the UNIX script driver machine. The 
time will be stored in a structure pointed to by p. The structure is 
defined in $EMPOWER/h/empowercs .h as: 



struct timevalue 


{ 




long sec- 


/* seconds since Jan 1 


1970 */ 


short hsec; 

} 


/* and hundredths of a 


second */ 



RETURN VALUE (not applicable) 
SEE ALSO Eventtime, Difftime 
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FUNCTION Timeout 

SYNTAX int Timeout (n, f) 

int n; 

int {*f) (); 

DESCR1PTION Parameters 

n An integer that specifies the elapsed time (in seconds) after which a 
timeout should occur 

f The function to execute when a timeout occurs 
Comments 

During script execution, Timeout { ) specifies if and when a timeout 
should occur during response reading from the server. The default 
function Timeout (300, continue) is inserted at the top of every 
EMPOWER/CS script created. You can change this default when editing 
your script file. 

To execute a script successfully, all events on the server must occur in 
the same way as they occurred during Capture. If an event occurs other 
than the set of expected events, the script will continue to wait for the 
expected events to occur. A timeout identifies expected events that do 
not occur. 

Occasionally, script execution can not continue because of unexpected 
events on the server or in Display mode the client or server. The 
resulting unexpected responses can identify an abnormal error, loss of 
data between the client and server, or an unexpected screen image. If 
your executing script encounters a timeout, a windowRcv ( ) may need 
to be modified. If a timeout occurs when an emulated user attempts to 
connect to the SUT, you should ensure that the database on the server 
is available. 

The function (f parameter) designated to handle the timeout condition 
can be either an EMPOWER/CS function or a user-defined function. 
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The two EMPOWER/CS functions are exit and continue. The exit 
function terminates the script. The continue function causes 
premature return from the executing function, and execution of the 
next function in the script. A user-defined function can be specified to 
handle a timeout if the exit and continue functions are not desirable. 

If a timeout occurs during script execution, review the log file to 
determine the cause. In some cases, the expected behavior did occur, 
but it took longer than the current timeout delay. If this is the case, you 
should edit the script to increase the timeout threshold with a new 
Timeout { ) function. 

By default, when a script executes, EMPOWER/CS does not display 
timeout information on the UNIX machine when a timeout occurs 
because the EMPOWER/CS function Unset (notify) is inserted in 
each script when it is created If you wish to display timeout information 
during script execution, use the Set (notify) function. 

Timeout ( ) returns the previous timeout value. An etimeout value 
will be returned by the executing function upon timeout 

The following is an example of how a Timeout() function may appear 
within a script 

Timeout (60, EXIT) ; 

SEE ALSO Dberror, Set, Unset 



RETURN VALUE 



EXAMPLES 
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FUNCTION Type 

SYNTAX Type (str, . ../* args */) 

char *str, *args 

DESCRIPTION Parameters 

str A string containing the characters typed at the PC 

args Optional variable arguments 

Comments 

The Type ( ) function is inserted into your script file during Capture 
when keystrokes are entered from the PC keyboard. The str 
parameter may include standard keyboard keys, except for those 
defined as MS Windows virtual key codes (such as vk_control, 
vk_escape, etc.) and the non-displayed key combinations defined 
below. Each key is translated into a KeyDown/Up pair for the emulation. 

Non-displayed key combinations are shown in the parameter of the 
Type() function using the standard UNIX technique in which the 
character * represents the Control key on the keyboard and the key 
combination Control-M ( a m) indicates a carriage return. Common control 
sequences captured into the Type ( ) function are listed below: 

A M Carriage Return 
A H Backspace 
A i Tab 

Delete 

During script execution in Display mode, the Type { ) function is used to 
emulate typing the specified keystrokes. In Non-Display mode, this 
function is used to emulate the type delay for typing the characters 
specified in str. 
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Note: You may edit this function to accept variable arguments in a way 
similar to the C function print f ( ) . The Type ( ) function will accept 
arguments so that data can be passed into the script from the command 
line. Arguments are passed to this function via the script execution 
statement. In the script execution command, arguments follow the 
names of the executable script file and the log file, and all arguments 
must be string pointers. The string conversion specification is provided 
by the characters %s. 

RETURN VALUE (not applicable) 

In the following Type ( ) function, the PC user typed the character c, 
then pressed the return key. The RETURN key is indicated by the 
characters A M. 

Type ( " c A M" ) ; 

Type strings are very easy to modify and can be edited to alter the 
keystrokes typed by an emulated user. For example, the following 
Type ( ) function is entered in a query: 

Type("13402 A M M ) ; 

It can be modified to: 

Type{ "8704^M" ) ; 



EXAMPLES 
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FUNCTION Typerate 

SYNTAX double Typerate (n) 

double n; 

DESCRIPTION Parameters 

n The typing speed measured in characters per second 

Comments 

Typerate { ) sets the emulated typing speed for a script. Typing speed 
is measured in characters per second. The default function 
Typerate (5) is inserted at the top of each script created by 
EMPOWER/CS. You may change this default when editing the script If 
you specify a type rate of zero, then no delay is used during script 
execution. Multiple Typerate ( ) functions may be used in a script to 
specify, for example, different type rates when using different 
applications. 

During script execution, each time that the emulated user is supposed 
to be typing at the keyboard, the script will pause a length of time 
defined as the number of characters to be typed times the type rate 
specified. For example, if the emulated user must type twelve 
characters and the type rate is specified as six characters per second 
(Typerate { 6 ) ) then the script will pause two seconds when the 
emulated characters are to be "typed." 

Care must be taken when inserting Typerate ( } functions into a script 
The response time statistics for scenarios and functions are generated 
from the user's perspective. Therefore, they will take into account the 
time it takes for the emulated user to enter information at the keyboard. 
This is particularly important when you are comparing the performance 
of similar scripts. Any Typerate ( ) functions inserted into one script 
must be inserted in the same locations in the other script(s) to provide a 
meaningful comparison. 
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If you specify rate less than zero, script will exit, receive an error 
message 

RETURN VALUE This function returns the old typerate value 



EXAMPLES In the following script segment, the type rate delay is set at 6 

characters per second: 



/* EMPOWER/CS VI. 0.1 Remote Terminal Emulator Script */ 



Typerate (5); /* Typing delay in CPS */ 

PointerrateQBO) ; /* Poin terra te in PPS */ 

Thin3cuniform(l ( 2.5); /* Think delay */ 

Seed(getpid() ) ; /* Seed random number generator */ 

Timeout (300, CONTINUE);/* What to do if function takes too long */ 

Dberror { CONTINUE ) ; /* What to do on Database errors */ 

Unset (NOTIFY) ; /* Don't display warnings. I'll use Mon to find them */ 

Beginscenario ( " f oo" ) ; 



SEE ALSO 



Pointerrate 
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FUNCTION Unset 

SYNTAX long Unset (n) 

long n; 

DESCRIPTION Parameters 

n The EMPOWER/CS option to be turned off 



Comments 

unset () turns off EMPOWER/CS options during script execution. 
Valid options are listed below: 



OPTION 


DESCRIPTION 


LCMD 


log miscellaneous commands 


FLUSH 


flush SUT responses to the log that are detected after a 




pattern match in a windowRcvO 


NOBUF 


don't use buffered writes to the log file 


NOTIFY 


display a message when a timeout occurs, execution is 




suspended, or execution resumes 


BELL 


ring the bell twice when a timeout occurs 


LOGGING 


enable logging 



Default options are lcmd and logging. 



RETURN VALUE Unset { ) returns a long value containing the previously set options. 
EXAMPLES The following examples demonstrate using Unset ( ) . 



Unset (FLUSH) ; 
Unset (LCMD) ; 



SEE ALSO Set 
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FUNCTION Username 

SYNTAX Username { lognum, username ) 

int lognum; 
char *username; 

DESCRIPTION Parameters 

lognum An identifier of a logon communication structure 

username A user name specified for logging on the SUT 
Comments 

The Username ( ) function is inserted into your script when a user name 
was entered to logon to the SUT, This function will occur before a 
Logon { ) function in your script 

During script execution, username ( ) sets the name of a user logging 
on to the database before a Logon ( ) function executes. 



RETURN VALUE If the function is successful, zero is returned. If an error occurs, -1 is 
returned. 



EXAMPLES In the following example, the user scott attempted to logon to the 

SUT: 



Type{ "scott^Itiger^IFOO^M" ) 

Username { LOG1 , " scot t@F00 " ) ; 
Password {L0G1, "tiger") ; 
Logon (0RACLE1, L0G1) ; 



SEE ALSO AppName, Hostname, Language, Password, Servername 
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FUNCTION 



WindowRcv 



SYNTAX 



void WindowRcv (pattern) 
char *pattern; 



DESCRIPTION Parameters 

pattern Command pattern for drawing windows on screen 

Comments 

The WindowRcv () function is inserted into the script file during 
Capture when an activated window is drawn on screen and usually 
follows an AppWait ( ) call. Consecutive WindowRcv ( ) functions may be 
inserted into the script during Capture, This function is used during 
script execution in Display mode to ensure that the activated window is 
drawn on screen. In Non-Display mode, this function is ignored because 
the AppWait () function simply emulates the time taken to draw the 
window. 

The parameters of this function are MS Windows standard two-letter 
pneumonics. The parameters can be any of the following commands: 



Command 

Cw 

Pt 

Dw 

Co 

Sf 

Ac 

Sz 



Description 
Create Window 
Paint 

Destroy Window 
Command 
Set focus 
Activate 

System Command 



RETURN VALUE (not applicable) 
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EXAMPLES The following example demonstrates typical windowRcv ( ) commands 

from a script file: 



AppWait (0 .05) ; 

WindowRcv ( "CwPtP tDwCoSfCwCwCwCwCwCwCwCwCwCwSf AcS z Pt" ) ; 
WindowRcv ( " PtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPtPt " ) ; 
Cur rent Window ( " Run ",429,491,880,764); 



SEE ALSO AppWait 
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3.0 Error Messages 

The following pages contain a list of warning and error messages that may be 
generated by EMPOWER/CS. 

Most of the warning messages generated by EMPOWER/CS will be preceded with 
the word warning and most error messages will be preceded with the word error. 

Usually, names of EMPOWER/CS tools and script names or IDs precede the 
warning and error messages. This feature helps you to locate the tool and script 
generating the warning or error message. 



"5 All warning and error messages are listed in alphabetical order followed by detailed 

01 descriptions and corrective actions. 
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All input files do not have the same unit of time 
The input files to Draw do not contain the same unit on the line identifying the 
duration of the reports. Make sure your input variable identifies the correct input 
files. Do not edit the . std files created by Report. 

Arithmetic operation invalid for type string 

An arithmetic operation (e.g., Gv__add ( ) ) was attempted on a character string type 
global variable. Only read and write operations are valid for character string 
variables. 



Attempt to obtain the time of an unknown event 

Eventtime ( ) was passed an invalid argument. Check script for mistyping. Make 
sure that you call Eventtime { } with an argument that is one of tbf, tef, tbs, or 

TES. 



Bad within value 

A -w argument to Report was followed by an invalid value. The value must specify 
a time in ss, mm:ss, hh:mm:ss format. The time can optionally be followed by a 
decimal point and an integer to identify a fraction of a second. Check the syntax of 
the Report command and rerun. 

Bars are not placed proportionally 

Draw was unable to separate the bars in a chart with space that is proportional to the 
number of users represented by each bar. Select a different set of input files with 
different numbers of users if you must have bars that are proportionally spaced. 

Bitwise operation invalid for type double 
Bitwise operation invalid for type float 
Bitwise operation invalid for type string 

A bit-wise operation (e.g., Gv_and( )) was attempted on a double, float, or character 
string type global variable. Only read, write, and arithmetic operations are valid for 



EMPOWER/CS-Vl.0.1 



3-2 

Copyright PERFORM!* Inc. © 1995 



User's Guide— Reference 



double and float variables. Only read and write operations are valid for character 
string variables. 

Bitwise relation invalid for type double 
Bitwise relation invalid for type float 
Bitwise relation invalid for type string 

A bit -wise relation (e.g., " | "&") was attempted on a double, float, or character string 
type global variable. Only logical comparisons are valid for these variable types. 

Can't accept duplicate characters. Try again 

Draw requested legend characters in interactive mode and you repeated one or 
more characters. Your characters must be unique. Enter a different set of 
characters. Enter quit to exit Draw. 

Can't accept duplicate selection. Try again 

Draw requested a set of choices in interactive mode and you repeated one or more 
of the choices. Your choices must be unique. Enter a different set of choices. Enter 
quit to exit Draw. 

Can't allocate global variable: different type already in use 
The global variable specified exists but is a different type than specified in the 
Gv_alloc ( ) statement. The "type" argument of Gv_alloc { ) must match the 
existing variable type. 

Can't attach to shared memory segment 

Can't change size of existing shared memory segment 

A problem occurred when attempting to access the UNIX script driver's shared 

memory segment. Check the access permissions of the segment with the ipcs 

shell command. Terminate the scripts and restart them. Removing the shared 

memory segment with ipcrm which will destroy the global variables and recreating 

them with gv_init may be necessary. 
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Can't continue. Draw exited 

Can't continue. Specification generated is stored in 
[specification] 

Can't continue. Specifications generated are stored in 
[specification] 

Draw encountered a condition that prevented it from continuing. Correct the 
condition. Specifications created prior to the error condition are saved in the file 
specified. 

* 

Can't create control semaphore 
Can't create shared memory segment 

A problem occurred when attempting to access the UNIX script driver's shared 
memory segment. Check the access permissions of the segment with the ipcs 
shell command. Terminate the scripts and restart them. Removing the shared 
memory segment with ipcrm which will destroy the global variables and recreating 
them with gv_init may be necessary. 

Can't create global variable: maximum exceeded 

An attempt was made to create an additional global variable beyond the limit allowed 
by default If more global variables are required, remove all existing variables with 
the gv_seg -r command which will destroy all global variables, then, with gv_seg 
newlimit where newlimit is a new number, create a new shared segment with a 
higher limit Use gv_stat -s to determine the current limit 

Can't create shared memory segment 

Can't detach from global variable segment 

A problem occurred when attempting to access the UNIX script driver's shared 
memory segment Check the access permissions of the segment with the ipcs 
shell command. Terminate the scripts and restart them. Removing the shared 
memory segment with ipcrm which will destroy the global variables and recreating 
them with gv_init may be necessary. 
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Can't detach from global variable segment 

A problem occurred when attempting to access the UNIX script driver's shared 
memory segment. Check the access permissions of the segment with the ipcs 
shell command. Terminate the scripts and restart them. Removing the shared 
memory segment with ipcrm which will destroy the global variables and recreating 
them with gv_init may be necessary. 

Can't exec [cc statement] 

Cscc is trying to execute the C compiler on your UNIX script driver. The C compiler 
is not in your path environment variable or does not have execute permission. 
Ensure that the C compiler can be executed at the command line. 

31 Can't find number of users in [input] 

^ An input file to Draw does not contain a line identifying the number of users in the 

^ report Make sure the input file is a . std file. Do not edit the . std files created by 

Jl Report. 

Can't find the specified event in all of the input files 
fil A Draw specification identifies an event that does not exist in all of the input . std 

EH files. An event is the name of a scenario or function. The event must exist in all 

Jzf input files. Correct the specification to identify an existing event Check spelling. 

^ Make sure your input variable identifies the correct input files. 

Can't find the specified event type in the input file 
A Draw specification identifies an event that does not exist in the input . std file. 
An event is the name of a scenario, function or transaction. Correct the 
specification to identify an existing event Check spelling. Make sure your input 
variable identifies the correct input file. 
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Can't find the specified field in the input file 
A Draw specification identifies a field that does not exist in the input . std file. 
Check spelling in the specification. Make sure your input variable identifies the 
correct input file. 

Can't find the specified field in all of the input files 
A Draw specification identifies a field that does not exist in all of the input . std 
files. Check spelling in the specification. Make sure your input variable identifies 
the correct input files. 

Can't find unit of time in [input] 

An input file to Draw is missing the line containing the duration of a report. Make 
sure your input variable identifies the correct input files. Do not edit the . std 
files created by Report. 

Can't find [file] 

Cscc can not find a function library or header file required for compilation. Make 
sure your empower environment variable is set to the location of the installed 
EMPOWER/CS software. Make sure the empower environment variable is 
exported. 

Can't fork 

Make sure the UNIX script driver kernel is configured with adequate resources to 
execute processes. Check the UNIX script driver console for kernel error 
messages. Typical resources that need increasing are the maximum number of 
processes in a system and the maximum number of processes per user. 

Can't get control semaphore 
Can't get shared memory segment 

A problem occurred when attempting to access the UNIX script driver's shared 
memory segment Check the access permissions of the segment with the ipcs 
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shell command Terminate the scripts and restart them. Removing the shared 
memory segment with ipcrm which will destroy the global variables and recreating 
them with gv„init may be necessary. 

Can't open /dev/null 

An attempt to open /dev/null failed. Make sure /dev/null exists on your UNIX 
script driver and has read and write permission. Make sure /dev/null is a special 
character device. 

Can't open current directory 

The name of the current directory can not be obtained. A call to getcwd( ) failed. 
Make sure the current directory has read permission. 

Can't open [log] for writing 

Log specified can't be opened. Check syntax of command to execute your script 
Check script table entries if you are executing scripts with Mix. Remember that a 
port must be specified to specify a log. Make sure the directory in which the log is 
being written has write permission for you. Make sure an existing copy of the log 
has write permission for you. 



Can 1 1 


open 


[input] 


Can* t 


open 


[output] 


Can' t 


open 


[mixlog] 


Can' t 


open 


[cscc* . o] 


Can' t 


open 


[script table] 


Can' t 


open 


[script .c] 


Can' t 


open 


[specification] 



An attempt to open a file failed. If the file is to be created, make sure you have 
write permission to the directory in which the file will be placed and write 
permission to an existing version of the file if the file exists. Make sure the file 
system in which the file is to be created is not full. If the file is to be read, make 
sure the file exists and that you have read permission on the file. 
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Can't read [file] 

Cscc can not read a function library or header file required for compilation. Make 
sure that you have read permission on the EMPOWER/CS libraries and header 
files. 



Can't rebind stdin of script 

EMPOWER/CS rebinds the standard input file descriptors of a script running in the 
background to prevent the script from receiving interrupt signals generated at the 
keyboard A dup ( ) function failed. The dup ( ) was interrupted by a signal or 
reached a maximum number of open files. Make sure there is an adequate number 
of open files permitted on the UNIX script driver machine and that the maximum 
number of open files per user is large. 



Can't re-initialize: global variable active or protected by other 
The gv_init command was entered to reset a variable which is in use or 
protected. Check for active scripts using the variable. If no scripts are running 
which use the variable, remove the variable before attempting the gv_init 
command again. 



Can't remove allocated variable 

The gv_rm command was used while the global variable was allocated to at least one 
script Wait for scripts to finish or use the -f option. 



Can't remove shared memory segment 
Can't remove shared semaphore segment 

A problem occurred when attempting to access the UNIX script driver's shared 
memory segment. Check the access permissions of the segment with the ipcs 
shell command. Terminate the scripts and restart them. Removing the shared 
memory segment with ipcrm which will destroy the global variables and recreating 
them with gv_init may be necessary. 
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Can't start [scriptid] 
Can't start [scriptid. n] 

A script identified in a script table can't be executed. The script is probably 
misspelled, not in your path environment variable, or does not have execute 
permission. Check syntax and spelling in the script table. Ensure that the script can 
be executed at the command line. 

Make sure the UNIX script driver kernel is configured with adequate resources to 
execute processes. Check the UNIX script driver console for kernel error 
messages. Typical resources that need increasing are the maximum number of 
processes in a system and the maximum number of processes per user. 

Can't stat shared memory segment 

A problem occurred when attempting to access the UNIX script driver's shared 
memory segment. Check the access permissions of the segment with the ipcs 
shell command. Terminate the scripts and restart them. Removing the shared 
memory segment with ipcrm which will destroy the global variables and recreating 
them with gv_init may be necessary. 

Can't unprotect global variable without protecting first 

A script executed the Gv_unprotect ( ) function when the specified variable had 

not been protected by the script 

Can't wait on self -protected global variable 

A script executed the Gv_waitwhile ( ) or Gv_waituntil ( ) function on a variable 
which the script has protected with Gv_protect ( ). A protected variable can not be 
updated by other scripts, so a Gv_waitwhile ( ) or Gv_wa it until { ) function 
probably will cause an indefinite delay. 

Character = not found; ignoring the line 

Draw encountered a keyword in a specification that was not followed by an = 
character. Check the specification. 
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Character [c] not found; ignoring the line 

Draw encountered a statement in a specification that did not contain a required 
character. Check the specification. 



Character string in the specification is too long 
The name of an event in an input file to Draw is too long. The maximum is 15 
characters. Make sure your input variable identifies the correct input files. Do not 
edit the . std files created by Report 



Characters should be separated with spaces 

The legend characters in a specification to Draw are not separated by spaces. 
Check the syntax of the legend statement in the specification. 



COMMENT too long. Ignored 

Draw requested a comment in interactive mode and your response identified one 
that is too long. Enter a shorter comment. Maximum comment is 60 characters. Enter 
quit to exit Draw. 



Current directory does not contain any ..STD files 

Draw can not find any files with the ..std suffix in the current directory. Make sure 

you are in the directory containing your . std files. 



Division by zero undefined 

The value zero was passed as the divisor argument to a Gv_div ( ) or Gv_mod ( ) 
function. 



Empty line. Try again 

Draw is requesting input in interactive mode and none was entered. Enter a 
response or type quit to exit Draw. 
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Error in [file] 

A specification or input file to Draw contains an error. A specific error message 
follows this error. Refer to the description of the specific error message for more 
information. 



Error near line [n] => [data] 

A specification or input file to Draw contains an error. A specific error message 
follows the => symbol. Refer to the description of the specific error message for 
more information. The line number n is often not correct. 



EVENT value is not defined properly 

A specification to Draw contains and invalid event statement Check syntax in the 
specification. 



Failed set all semctl 

A problem occurred when attempting to access the UNIX script driver's shared 
memory segment. Check the access permissions of the segment with the ipcs 
shell command. Terminate the scripts and restart them. Removing the shared 
memory segment with ipcrm which will destroy the global variables and recreating 
them with gv_init may be necessary. 



Forced to use HIDDEN format 

A Draw specification requested bars to be drawn in clustered format Draw was 
unable to fit all of the bars on the chart Draw changed format to hidden. Reduce 
the number of bars to be drawn if you want the chart in clustered format 



Forcing protection of global variable protected by other 

The gv__protect command was used with the -f option while the global variable 

was protected by a script 
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Forcing unprotection of global variable protected by other 

The gv_unprotect command was used with the -f option while the global variable 
was protected by a script. 

Format incorrect. Try again 

Draw requested input in interactive mode and your response was entered in an 
unacceptable format. Correct the format and retry. Enter a response or type quit to 
exit Draw, 

Global variable already allocated 

A script attempted to allocate access to a variable which has already been allocated 
to the script Each variable may be allocated only once in each script unless it has 
been de-allocated with Gv_f ree ( ) . 

Global variable already protected 

A script attempted to protect a variable that is already protected. The variable must 
be unprotected before it can be protected again. 

Global variable does not exist 

A specified variable was not created with the gv_init command, or was removed 
with the gv_rm command 

Global variable name allocation problem 

Generally, this error is caused when a fork ( ) system call has been executed after 
a variable was allocated to the script. If this error occurs, you can not fork ( ) after 
allocating variables. 
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Global variable not currently allocated 

A Global Variable function specified a variable that is not currently allocated to the 
script You must allocate a variable with the Gv_alloc ( ) function before using the 
variable. 

Global variable protected by other process 

The gv_protect command was executed to protect a variable which is currently 
protected by a script 

Illegal global variable check type 

An illegal check type was specified. Use only the commands and functions 
specified in this reference manual. 

Illegal global variable relation 
Illegal global variable relation length 
Invalid global variable relation 

An illegal relation string was used with the Gv_tes t ( ) , Gv_waitwhile ( ) , or 
Gv_waituntil() function. 

Illegal return value from semop/ctl call 

A problem occurred when attempting to access the UNIX script driver's shared 
memory segment Check the access permissions of the segment with the ipcs 
shell command. Terminate the scripts and restart them. Removing the shared 
memory segment with ipcrm which will destroy the global variables and recreating 
them with gv_init may be necessary. 

Incomplete specification — required fields undefined 

Draw encountered a specification that did not contain the required statements 

input, x, Y and event. Correct the specification. 
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Incomplete statement in the specification. Defaults will apply 
Draw encountered a specification that did not contain a properly formatted 
statement. Correct the specification. 

INPUT file does not contain proper data 
INPUT files do not contain proper data 

One of the input files to Draw contains erroneous data. Make sure you specify 
. std files created by Report as input. Do not edit the . std files that are to be used 
by Draw. 

Input file has too many columns 

Draw encountered an input file that had more that 20 columns of possible Y values. 
The maximum in a . std file is 20. Create the . std files with fewer y values and 
retry. 

INPUT was redefined; the last one will override 

More than one input statement was encountered in a specification to Draw. Draw 
will use the last one found. Correct the specification. 

Invalid character in name of function 

A BeginfunctionO or Endf unction ( ) function contained unprintable characters. 
Check the argument of the failing function. The argument must be a string. 

Invalid character in name of scenario 

A Beginscenario { ) or Endscenario ( ) function contained unprintable characters. 
Check the argument of the failing function. The argument must be a string. 
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Invalid choice. Try again 

Draw requested input in interactive mode and your response was not one of the 
possible choices. Enter a choice from the list displayed by Draw. Enter quit to exit 
Draw. 

Invalid global variable name length 

The name of the variable is either too long or was not specified. The maximum 
name length is 14 characters. 

Invalid global variable operation 

An invalid operation was specified. Use only the commands and functions specified 
in Section 7 EMPOWER/GV of the Multi-User Testing manual. 

Invalid global variable type 

An invalid variable type was specified. The type specification must match one of 
the valid variable types specified in Section 7 EMPOWER/GV of the Multi-User 
Testing manual. 

Invalid number of characters to seek 

A Seek ( ) function was called with an invalid argument The argument must be an 
integer or floating point greater than or equal to zero. Check the argument of the 
failing function. 

Invalid specification -- BEGIN statement expected 

Draw encounted a specification that did not begin with a begin statement Check 

the specification. Make sure you are identifying the correct specification. 
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Invalid timeout value 

A Timeout ( ) function was called with an invalid argument. The argument must be 
an integer or floating point greater than or equal to zero. Check the argument of the 
failing function. 

Invalid values in think time distribution 

A Thinkcons tant { ) , Thinkuni form ( ) , or Thinktne ( ) function was called with 
one or more invalid arguments. The arguments to one function must be ascending 
in value since they specify minimum, average and maximum values in sequence. 
Remember that Thinkconstant ( ) requires one argument, Thinkuni form { ) 
requires two arguments, and Thinktne { ) requires three arguments. Check the 
^ arguments of the failing function. 

LEGEND was redefined; the last one will override 
^ More than one legend statement was encountered in a specification to Draw. Draw 

yg will use the last one found Correct the specification. 

Missing quote 

py A line in the script table does not contain an even number of " characters. The - is 

y f used when specifying arguments to scripts in the script table. Check the syntax of 

2 yo ur script table. 

Missing script id 

A line in the script table does not contain a script ID. Make sure you have identified 
the proper script table on the Mix use command. Check syntax of lines in the script 
table. Remember that comments in the script table begin with a # character. 

Modulo operation invalid for type double 

Modulo operation invalid for type float 

Modulo arithmetic is not permitted for double or float type variables. 
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Must specify m before w 

The -m option of Report must occur before the -w option. Check the syntax of the 
Report command and rerun. 

N/A values in INPUT file 

Draw encountered an input file than contained the n/a symbol for a data value that 
you requested. The n/a is generated by Report if the event never occurred during 
the emulation. Rerun the emulation and make sure that the event requested occurs 
at least once or select a different event to chart. 

Negative thinktime value 

A Thinkconstant ( ) , Thinkunif orm ( ) , or Think tne ( ) function was called with 
one or more invalid arguments. The arguments must be integers or floating points 
greater than or equal to zero. Remember that Thinkconstant { ) requires one 
argument, Thinkunif orm ( ) requires two arguments, and ThinktneO requires 
three arguments. Check the arguments of the failing function. 

No help available, recompile without -h option. 

A script was compiled with the -h option of Sec and subsequently executed with an 
invalid argument The help information regarding the usage of arguments was not 
compiled in the script Check the syntax of the command used to start the script or 
compile the script without the -h option to Sec and rerun. 

No more comments allowed 

The maximum number of comments in a specification to Draw was exceeded. The 
maximum number is 50. Reduce the number of comments. 
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Not enough room for CLUSTERED format 

A Draw specification requested bars to be drawn in clustered format Draw was 
unable to fit all of the bars on the chart Draw changed format to hidden. Reduce 
the number of bars to be drawn if you want the chart in clustered format 

Number incorrect. Try again 

Draw requested input in interactive mode and your response was not one of the 
possible choices. Enter a choice from the list displayed by Draw. Enter quit to exit 
Draw. 

Number of LEGEND characters incorrect. 

The legend characters in a specification to Draw are not separated by spaces. 
Check the syntax of the legend statement in the specification. You should specify 
one legend character for each y value specified 

Number of users not distributed well 

Draw was unable to separate the bars in a chart with space that is proportional to the 
number of users represented by each bar. Select a different set of input files with 
different numbers of users if you must have bars that are proportionally spaced, 

ORGANIZE value not defined properly. Default of CLUSTERED will 
apply 

Draw encountered a specification that did not contain an organize statement that 
was properly formatted. Correct the specification. 

ORGANIZE was redefined, the last one will override 

More than one organize statement was encountered in a specification to Draw. 

Draw will use the last one found. Correct the specification. 
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Out of memory 

The UNIX script driver machine is out of virtual memory. 
Percentile out of range 

A -p argument to Report was followed by an invalid value. The value must be an 
integer greater than zero and less than or equal to one hundred. Check the syntax 
of the Report command and rerun. 

Performance measures in [input] not consistent 

The input files to Draw do not contain the same set of Y values generated by 
Report. Make sure that you use the same set of -p and -w options to Report when 
creating each of the . std files used as input to Draw. Make sure your input 
variable identifies the correct input files. 

Reached another BEGIN before keyword END 

Draw encounted a begin statement in a specification before an end statement 
terminated the current specification. Check the specification. Make sure you are 
identifying the correct specification. 

Reached end of file before keyword END 

Draw encounted the end of a specification before an end statement terminated the 
current specification. Check the specification. Make sure you are identifying the 
correct specification. 

Received signal n 

EMPOWER/CS received a signal that it was not expecting. The signal was probably 
generated by pressing the interrupt key, e.g. A c, a kill command or after 
detecting the disconnection of a terminal. Prevent the signal from recurring and 
rerun. You can locate the meaning of the signal in /usr/ include/ sys/ signal .h. 
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Removing allocated variable 

The gv_rm command was used with the 

to at least one script 



-f option while the variable was allocated 



Resumed at [99:99:99.99] 

Execution of a script is continuing following a Suspend ( ) function. The script was 
resumed from Mix, Monitor, or with a kill command. 

Semctl call failed 
Semop/ctl failed 
Semop/ctl call failed 

A problem occurred when attempting to access the UNIX script driver's shared 
memory segment. Check the access permissions of the segment with the ipcs 
shell command and increase the number of semaphore undo structures (sem undo 
or sem nu-These structures are UNIX kernel parameters). Terminate the scripts 
and restart them. Removing the shared memory segment with ipcrm to destroy the 
global variables and then recreating them with gv_init may be necessary. 

Source [ script. c] newer than binary, execution continues. 
A script detected that the source version of the script has a later modification date 
than the binary version. The source version may have been changed and requires 
a recompilation. Recompile the source version of the script or move the script to 
another directory to eliminate the warning. 

The script looks in the current directory for the source version. The name of the 
source version is formed by adding a .c to the name of the binary. 

Suspended at [99:99:99.99] 

Execution of a script is suspended because of execution of the Suspend () 
function or Monitor. Script execution will pause until the script is resumed. 
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Timeout occurred at [99:99:99.99]. execution continues. 
The timeout condition in a script was set to continue. A timeout occurred while 
the script was waiting for a response from the SUT. The expected response from 
the SUT was not received You should examine the log created by the script and 
determine whether or not the response was valid. 

Timeout occurred at [99:99:99.99], execution terminated. 
The timeout condition in a script was set to exit. A timeout occurred while the 
script was waiting for a response from the SUT. The expected response from the 
SUT was not received. You should examine the log created by the script and 
determine whether or not the response was valid. 

TITLE must contain 60 or fewer characters 

A title in a specification to Draw is too long. The maximum is 60 characters. 
Reduce the number of characters in the title. 

Too few values. Both YMIN and YMAX are required 

Draw requested a ymin and ymax in interactive mode and your response did not 
specify both. Enter both values in integer or floating point format. Enter quit to 
exit Draw. 

Too many arguments in cc statement 

The maximum number of arguments that can be passed to a cc statement by Cscc 
is 99. The limit has been exceeded. Decrease the number of arguments by 
modifying your e_cflags and e_libs environment variables. 

Too many arguments specified — extras were ignored 

Draw encountered a statement in a specification that contained too many 

arguments after a = character. Check the syntax of the specification. 
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Too many comments . Ignored the previous one 

The maximum number of comments in a specification to Draw was exceeded. The 
maximum number is 50. Reduce the number of comments. 

Too many fields. Only one field required 

Draw requested input in interactive mode and your response identified too many 
choices. Enter only one choice from the list displayed by Draw. Enter quit to exit 
Draw. 

Too many fields . Select up to 3 fields . Try again 
Draw requested input in interactive mode and your response identified too many 
choices. Enter only up to three choices from the list displayed by Draw. Enter quit 
to exit Draw. 

Too many files. Select up to 59 files. Try again 
Draw requested input in interactive mode and your response identified too many 
choices. Enter only up to 59 choices from the list displayed by Draw. Enter quit to 
exit Draw. 

Too many INPUT files extras were ignored 

A specification to Draw identified too many input files. The maximum number of 
input files is 59. Reduce the number in the specification. 

Too many LEGEND characters — extras were ignored 

A specification to Draw identified too many legend characters. There should be 

one legend character for each y value. Reduce the number in the specification. 

Too many ORGANIZE values — extras were ignored 

A specification to Draw identified too many organize values. There should be 

only one organize value. Reduce the number in the specification. 
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Too many processes 

Maximum number of processes per user on the UNIX script driver machine has 
been reached Make sure there is an adequate number of processes permitted on 
the UNIX script driver machine and that the maximum number of processes per 
user is large. Reconfigure the UNIX kernel on the UNIX script driver and rerun. 

Too many values. Only YMIN, YMAX required 

Draw requested a ymin and ymax in interactive mode and your response specified 
more than the two values. Enter two values in integer or floating point format. Enter 
quit to exit Draw. 

Too many warnings — additional warnings will not be displayed 
Draw generated too many warnings during a single execution. Correct the 
conditions that are causing the warnings. 

Too many within values 

More than 100 within values were specified on one command line to start Report 
Reduce the number of within values or check the syntax of the Report command 
and rerun. 

Too many X values — extras were ignored 

A specification to Draw identified too many x values. There may be up to 59 x 
values. Reduce the number in the specification. 

Too many Y values extras were ignored 

A specification to Draw identified too many y values. There may be up to three y 
values. Reduce the number in the specification. 
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Unexpected suspend request 

A global variables shell command received a signal from a kill command or 
process. Someone else may be trying to kill your process. 

Unit of time inconsistent. Try again 

The input files selected Draw do not contain the same unit on the line identifying 
the duration of the reports. Select a different set of input files from the list 
displayed by Draw. Do not edit the . std files created by Report. 

Unit of time inconsistent in [input] 

The input files to Draw do not contain the same unit on the line identifying the 
duration of the reports. Make sure your input variable identifies the correct input 
files. Do not edit the . std files created by Report 

Unrecognized keyword line ignored 

Draw encountered a statement in a specification that did not begin with a valid 
keyword Check the specification. Make sure the keywords are followed by a space 
and a = character. 



Value conversion failed 

The value passed could not be converted to the variable type. 

Value in the input file is missing N/A assumed 

Draw encountered an input file than did not contain a y value for an event that you 

requested. Rerun the emulation and make sure that the event requested occurs at 

least once or select a different event to chart. Do not edit the . std files created by 

Report. 
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Value string exceeds maximum length of a global variable string 
A string argument was longer than the maximum allowed for global variable strings. 
Global variable strings must be no longer than 32 characters. 



Within value out of range 

A -w argument to Report was followed by an invalid value. The value must be 
greater than zero. Check the syntax of the Report command and rerun. 



X axis TITLE must contain 30 or fewer characters 

Draw requested an xtitle in interactive mode and your response identified one 

that is too long. Enter a shorter xtitle. Enter quit to exit Draw. 

43 X was redefined; the last one will override 

2 More than one x statement was encountered in a specification to Draw. Draw will 

/5 use the last one found. Correct the specification. 



Y axis TITLE must contain 30 or fewer characters 

Draw requested a ytitle in interactive mode and your response identified one 

that is too long. Enter a shorter ytitle. Enter quit to exit Draw. 



Y values are not consistent 

The Y values specified to Draw do not have the same unit of measure. For 
example, you are trying to place average response time and throughput on the 
same chart. Select a different set of y values. 



Y was redefined; the last one will override 

More than one Y statement was encountered in a specification to Draw. Draw will 
use the last one found. Correct the specification. 
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4.0 EMPOWER/CS Technical Support 



Contact PERFORMIX Technical Support if you experience problems with any 
aspect of EMPOWER/CS. For problems with script development, script execution, 
reporting, or other operational aspects of EMPOWER/CS, please have the following 
information at hand when you contact us: 



To determine your software version and serial numbers, use any EMPOWER/CS 
too! to display the copyright banner. For example: 



Cscc: EMPOWER/CS VI . 0 . 1 , Serial#ROOOOO-000 , Copyright PERFORMIX, Inc. 

1988-95 

Usage : 



EMPOWER/CS software is identified with a three-digit version number, such as 
"LOT. The first digit represents the major version cycle, the second digit 
represents the minor version cycle, and the third digit represents the patch level. 
This patch level increases with bug fixes. 

The serial number displayed in the copyright banner has two elements. The first 
portion identifies the five-digit software license number and is used by 
PERFORMIX support personnel to identify your particular platform, restrictions, and 
terms and conditions. The second part of the serial number identifies the copy 
number. The letter preceding the serial number identifies the type of license (i.e., 
"R" for regular, "S" for site, etc.). 

When calling for technical support, you will need to give both the three digit 
version number and the entire serial number. 



O 
O 

o 
o 
o 

O 



Any relevant script files 

Any relevant log files 

The Mix table 

The Mix log file 

Your software Version Number 

Your software Serial Number 
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You may contact the PERFORMIX main office at (703) 448-6606 between 9:00 am 
and 5:00 pm Eastern time. 

For your convenience, you also may request help by fax at any time of day or 
night. The PERFORMIX main office fax number is (703) 893-1939. In your fax, 
include the software version and serial numbers, a thorough description of the 
problem, and any supportive data (e.g., scripts, error messages, etc.). 

You also may email relevant information to support@performix.com. 
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for 




Client/Server 
Applications 






The testing process 



Applications that 
are not load tested 
often fail during 
the pilot stage - 
and consequently 
BUST at full-scale 
deployment 



The testing process is integral to successful application development. It consists of three stages 
regression, load and pilot testing— of which load testing is the keystone. 






Successful Application Development 



The complete testing process is a triumvirate 
of regression, load and pilot testing. The 
process should, ideally, be completed in 
that order. 

Regression testing (also called functional or 
quality testing) helps avoid errors linked to 
a single user. It is a linear process that 
examines virtually all pathways through an 
application. Since regression testing quickly 
isolates inconsistencies in the interface, it is 
particularly useful as applications are slightly 
changed. Sometimes a bit of tweaking in one 
area produces adverse affects in seemingly 
unrelated spots. 

Load testing analyzes the effect of many 
users upon an application. Conscientious 
load testing during the development process 
protects the application from failing under 
the weight of simultaneous users. Applied 
early in the development process, load testing 
gives developers an opportunity to correct 
problems — even if it means changing an 
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the problems become virtually too expensive 
to change. 

Once deployed, it is crucial that an 
application works without interruptions 
and delays. Load testing charts response 
time, enabling a developer to recognize those 
facets of a program that hinder performance. 
As well, load testing ensures scalability, 
paving the way for a company's growth. 

Pilot testing (otherwise known as beta testing) 
is the dress rehearsal before the show, the 
last step before full-scale deployment. It is 
the determination and culmination of a long, 
arduous development process. In a pilot test, 
an application is used by a subset of real 
users. These users exercise the common 
portions of the application and determine its 
effectiveness in helping them conduct 
business more competitively. Applications 
that have not been adequately load tested 
often fail during the pilot stage — and 
consequently crumble during full-scale 
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Load testing 



Load testing is a "no+brainer" 

Load testing is an essential step in your 
application development process. It affirms 
the success of your application by eliminating 
guesswork about quality and performance. 
By emulating multiple users simultaneously 
accessing an application, it quantifies the 
number of users your application can support 
and shields your company against slow 
response time and application failure. 

Even the most organized and well thought- 
out development is certain to have inherent 
weaknesses. In complex applications, these 
weak spots are often hidden. Load testing 
ferrets out these defects and shows you how 
to correct them. 

Without load testing, you can merely surmise 
about the performance of your application 
under the stress of many users. Why make 
an assumption when you can be certain? 
With load testing, you ascertain the inevitable 
problems embedded in your application 
during the development process, when the 
comparative cost of change is minimal. 



Knowledge is power 

The knowledge that arises from a load test 
helps you eliminate guesswork. By emulating 
many users, you determine, first and foremost, 
if yogr application will support its intended 
audience. 

Time is money 

Second, you pinpoint the time each user 
must wait for his or her screen response. 
Competitiveness depends on your company's 
ability to do things faster and more 
efficiently. 

Change is inevitable 

Third, you are primed for growth. The 
growing pains that naturally accompany 
success need not extend to your application. 
Load testing enables you to check and 
maintain your application as it grows, 
so you know if and when to adjust 
accordingly. 




If you think you don't need load testing, keep in mind the following risks. 
Few businesses can afford them. 



• The cost to repair, replace and rework your application after deployment usually exceeds the cost 
of testing the application. 

• An application deployed prematurely causes work stoppages. When a mission-critical application 
halts, a company loses precious time, revenue and customers. 



Benefits of EMPOWER 



EMPOWER your 
application with 
multi-user quality, 
performance and 
scalability 
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EMPOWER ensures that your application 
will run — and run smoothly. 

EMPOWER secures application performance 
for today and positions your business for 
tomorrow. 

EMPOWER finds application problems before 
they become dangerous. It guarantees the 
productivity of your employees. It prepares 
your business for change and growth. 

Multi'Xiser quality 

Using one UNIX 
machine to simulate 
hundreds of users, the 
EMPOWER line of 
testing products 
creates scripts to 
represent actual users and their daily, often 
disparate, operations. EMPOWER captures 
user activities — including the actual 
keystrokes, mouse movements and SQL 
requests that your employees generate while 
using an application — and creates emulation 
scripts. Then, EMPOWER arranges a mix of 
scripts to represent the many users your 
application must sustain. 

EMPOWER reveals if, and to what degree, your 
application works. Moreover, it enables you 
to fix intrinsic problems before deployment. 
You can correct difficulties that occur when 

► application code competes with other 
code for resources 

► access to data is simultaneous 

► your database and OS run out of resources 

► communication subsystems falter 




Performance 

Hardware, software, 
database and 
middleware 
vendors all laud 
the speed of their 
products. 

EMPOWER verifies 
those claims for your primary transactions, 
at your peak hours of business. When 
you test your application with EMPOWER, 
you know the exact time your users must 
wait for critical responses, and where 
application errors occur. 

Bottlenecks become easy to find and simple 
to correct. When response time does not 
meet requirements, developers can react 
quickly and calmly to solve the problem. 
EMPOWER permits them to 

► enhance application code 

► repartition code and data between 
client and server 

► optimize database parameters 

► size the CPUs and memory 

► adjust disk layout 

Scalability 

Likely, your 
business will 
grow and 
change. 

Already, you have 
invested money and effort in an application 
to fulfill your present needs. Why not confirm 
its ability to sustain progress? EMPOWER 
determines the outcome, with respect to 
quality and response time, when your 




application is forced to support a greater 
load. You can alter the user level, transaction 
mixes and rates, and complexity of the 
application. 

EMPOWER is the only true way to verify 
both the scalability of components and the 
scalability of components as they work 



together. EMPOWER ensures that you can 
simply and effectively determine capacity 
when changing 

► workload 

► application code 

► database size 

► hardware configurations 

► software revisions 



Script-and-go technology 



EMPOWER employs script-and-go 
technology to build the scripts you need 
to load test Script-and-go technology 
slashes the time needed for script 
development, making load testing simple 
and fast. As well, it guarantees the accuracy 
of your test results by replicating actual 
user activity. 

EMPOWER sits between the user device — 
whether it be a PC with a client, an X- 
terminal or simply a VT1 00 — and listens to 
the traffic between that device and your 
application. Based on the flow, EMPOWER 
builds a script that can replace the user 
device and drive your application. 

EMPOWER scripts can be replayed with or 
without user devices. Running scripts with 
user devices aides debugging. Running 
scripts without user devices relieves you 
from the burden of acquiring a lot of 
hardware for a multi-user test. 




EMPOWER uses the same language for scripts 
that execute with or without user devices. In fact, 
there is only one script for which you select the 
execution mode. 

With EMPOWER, you can readily extend captured 
scripts with loops, randomize script content with 
if-then-else and switch statements, vary the data 
in updates and queries, and govern script 
throughput with thinking, typing and pacing 
delays. Unique script-and-go technology is 
streamlined for load testing. It minimizes script 
development time and maximizes your opportunity 
for enhancing quality and performance. 




The EMPOWER family of products 



Improve the quality 
and performance of 
your client/server 
applications with 
superior load 
testing software 



Performix provides load testing software for 
a complete myriad of architecture — from 
simple character-based applications to 
complex, multi-tier client/server 
superstructures. The EMPOWER family 



of products has tested thousands of 
applications on a vast array of hardware, 
it supports all major databases, operating 
systems, networks and application 
development tools. 



Traffic captured 
and replayed 



EMPOWER 



EMPOWER/X EMPOWER/CS 



Interface of 
application to 
be tested 



Character 



Keystrokes 



X-Window 



X protocol 



Windows," Windows NT™ 
OS/2" and more 

Object-oriented events 
and SQL 



Performix facts 




Performix, Inc., was founded in 
1987 with the vision that load 
testing would become an 
integral part of every application develop- 
ment process. In the past eight years, the 
number of companies embracing load testing 
has skyrocketed and now includes virtually 
all businesses with mission-critical 
applications. Today, Performix is a privately 
held and funded company with sales and 
support offices across the United States 
and in Europe. 

All of the premier hardware vendors rely 
on Performix for their load testing needs, 
including HP, IBM, Sun, SCI, Sequent, 
Pyramid, NCR and DEC. Most of these 
vendors discarded in-house load testing 



software in favor of EMPOWER, and saved 
considerable time and money doing so. 
The major database vendors, such as 
Oracle, Sybase and Informix, also depend 
on the technical prowess of EMPOWER. 

Also relying on Performix are leading 
development companies across all major 
industries. Some of these prominent 
customers are AT&T, British Telecom, 
Sprint, Telia Data, Dow Jones, Fidelity 
Investments, Standard & Poors, Signet 
Bank, Mobil, Federal Express, DHL, Hyatt 
and Computer Associates. As well, major 
service organizations, such as Andersen 
Consulting, EDS and CSC, count on 
Performix to guarantee the success of 
their projects. 



Copyright© 1995 PERFORMIX. Inc -Ml rights r«er\r-d 
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